DEPRECATED
API REFERENCE
GENERAL
Introduction
SAP Concur APIs allow clients or partners to access data and functions within the SAP Concur product ecosystem. Through the use of these exposed endpoints and functions you can solve a vast array of different business issues and reporting needs such as:
- Pull data from SAP Concur for in-depth reporting services.
- Reconcile or validate your data by comparing SAP Concur data to what you have.
- Post new data into SAP Concur allowing for programmatic creation of information.
- Update existing information in SAP Concur to match your system data.
How to Use the APIs
SAP Concur APIs are accessed via an endpoint or URL. For some of our APIs the endpoint will accept parameters that will help refine the results being returned or allow for the insertion or update of data in the SAP Concur system.
Most of the SAP Concur APIs support four different types of requests:
- GET – Used to query information within the SAP Concur system.
- POST – Used to insert data into the SAP Concur system.
- PUT – Used to update existing information in the SAP Concur system.
- DELETE – Used to delete or deactivate existing information in the SAP Concur system.
SAP Concur also supports an alternative type of API referred to as a Callout. The Callout is a pre-configured step or condition that triggers SAP Concur to make a call out to your app to facilitate some sort of business transaction.
Explore the APIs
For the basic information on the APIs and what they do, you can check out the Swagger docs in API Explorer. Need more in-depth information? You can find information on each API using the links on the left side of the page. Finally, there are some Integration Guides that describe specific workflows. Even if none of them maps to your use case, they’re a good way to learn how to work with the SAP Concur APIs.
Resources
The information in these overviews will provide insight into what to expect during the certification process:
NOTE: These do not apply to a Triplink app integration.
HTTP Status Codes
Successful Requests
The web services return a HTTP 2xx response code when the request was successful.
HTTP Success Codes:
| Success Code | Message | Description |
|---|---|---|
| 200 | OK | The request was received successfully. |
Failed Requests
The web service should return a response within 60 seconds. If the request times out without a response, the application should wait for 5 minutes then retry the request.
The web service returns a 4xx or 5xx HTTP response code when there are any errors and will include the following elements:
| Element | Description |
|---|---|
| StatusCode | The HTTP error code. |
| Content | A parent element that contains an Error child element. |
Error elements
| Element | Description |
|---|---|
| Message | The error message. |
| Server-Time | The time the error was generated, based on the SAP Concur server's time zone. |
| Id | The ID of the error within Concur. |
Refer to the individual function documentation for function-specific error formats.
HTTP Error Codes
The full list of possible HTTP error codes can be found here. The table below provides additional details for commonly encountered error codes.
| Error Code | Message | Description |
|---|---|---|
| 400 | Bad Request | This response is returned if any of these conditions is true: * The specified URI is invalid. * The request is not formatted correctly. * The request is missing a required field. * The number of requests received exceed the request limit. * The request encountered a database deadlock. In this case, the developer should resend the request a short time later. * This error can be received if Chunked Transfer-Encoding is enabled by the developer's web server. Concur does not support Chunked Transfer-Encoding. Attendee Web Service: * The batch type parameter is not included on the URI of batch operations. * The request contains 0 attendees. * The request contains over 1000 attendees. Imaging Web Service: * The barcode or reportId is missing. Purchase Order Web Service: * The request contains 0 purchase orders. * The request contains over 1000 purchase orders. List Item Web Service: * The request contains 0 list items. * The request contains over 1000 list items. Payment Batch File: * The Batch ID specified in the URI is invalid. Trip Approval: * The request contains 0 itineraries. User Web Service: * The request contains 0 users. * The request contains over 1000 users. |
| 401 | Unauthorized | The Authorization header is not included in the request. |
| 403 | Forbidden | This response is returned if any of these conditions is true: * The Authorization header is included but it fails validation. This can happen if the OAuth consumer does not have access to the Concur product required by the web service. * The partner application associated with the oauth_consumer_key has not been allowed access to the requested company. * The Oauth token has expired or been revoked. |
| 404 | Not Found | Extract Web Service: The Definition ID or Job ID specified in the URI is invalid. Imaging Web Service: No image was found for the specified report Id or barcode. Itinerary Web Service: The Trip ID or Booking ID specified in the URI is invalid. Payment Batch Web Service: The Batch ID specified in the URI is invalid. |
| 409 | Conflict | Extract Web Service: A job for the specified definition is already queued or running. |
| 429 | Too Many Requests | This response is returned when services are overloaded either with too many requests from a single source or too many requests in aggregate. When this happens slow the rate of requests. |
| 500 | Internal Server Error/Not Closed | Expense Report Web Service: This response is returned when the system is unable to calculate an exchange rate for a posted expense report entry. Payment Batch Web Service: The specified batch could not be closed. |
| 503 | Service Unavailable | This response is returned when the web service is down for maintenance. The partner application should sleep for 5 minutes then retry the request. If the request continues to fail after a few retries, the developer should contact concurconnecttech@concur.com. |
Locale Codes
All Concur customers have the following locale set in their entities by default. This is the only locale that is available for all clients.
Default Locale
| Locales | Code |
|---|---|
| English (United States) | en_US |
Customers can request to have additional locales added to their entity if necessary. The following list includes all supported locales.
| All Supported Locales | Code |
|---|---|
| Bulgarian (Bulgaria) | bg_BG |
| Chinese (China) | zh_CN |
| Chinese (Hong Kong) | zh_HK |
| Chinese (Taiwan) | zh_TW |
| Croatian (Croatia) | hr_HR |
| Czech (Czech Republic) | cs_CZ |
| Danish (Denmark) | da_DK |
| Dutch (Belgium) | nl_BE |
| Dutch (Netherlands) | nl_NL |
| English (Australia) | en_AU |
| English (Canada) | en_CA |
| English (India) | en_IN |
| English (Ireland) | en_IE |
| English (New Zealand) | en_NZ |
| English (South Africa) | en_ZA |
| English (United Kingdom) | en_GB |
| English (United States) | en_US |
| Finnish (Finland) | fi_FI |
| French (Belgium) | fr_BE |
| French (Canada) | fr_CA |
| French (France) | fr_FR |
| French (Luxembourg) | fr_LU |
| French (Switzerland) | fr_CH |
| German (Austria) | de_AT |
| German (Germany) | de_DE |
| German (Luxembourg) | de_LU |
| German (Switzerland) | de_CH |
| Hungarian (Hungary) | hu_HU |
| Indonesian (Indonesia) | id_ID |
| Italian (Italy) | it_IT |
| Italian (Switzerland) | it_CH |
| Japanese (Japan) | ja_JP |
| Korean (North Korea) | ko_KP |
| Korean (South Korea) | ko_KR |
| Norwegian (Norway) | no_NO |
| Polish (Poland) | pl_PL |
| Portuguese (Brazil) | pt_BR |
| Romanian (Romania) | ro_RO |
| Russian (Russian Federation) | ru_RU |
| Slovak (Slovakia) | sk_SK |
| Spanish (Argentina) | es_AR |
| Spanish (Bolivia) | es_BO |
| Spanish (Chile) | es_CL |
| Spanish (Colombia) | es_CO |
| Spanish (Costa Rica) | es_CR |
| Spanish (Dominican Republic) | es_DO |
| Spanish (Ecuador) | es_EC |
| Spanish (El Salvador) | es_SV |
| Spanish (Guatemala) | es_GT |
| Spanish (Honduras) | es_HN |
| Spanish (Mexico) | es_MX |
| Spanish (Nicaragua) | es_NI |
| Spanish (Panama) | es_PA |
| Spanish (Paraguay) | es_PY |
| Spanish (Peru) | es_PE |
| Spanish (Puerto Rico) | es_PR |
| Spanish (Spain) | es_ES |
| Spanish (Uruguay) | es_UY |
| Spanish (Venezuela) | es_VE |
| Swedish (Sweden) | sv_SE |
| Thai (Thailand) | th_TH |
| Turkish (Turkey) | tr_TR |
Spend Category Codes
The following table lists Spend Category codes that are used in several of the Concur APIs.
| Code | Name |
|---|---|
| ADVTG | Advertising/Marketing |
| AIRFE | Airline Fee |
| AIRFR | Airfare |
| CARRT | Car Rental |
| COCAR | Company Car - Fixed Expense |
| COCRM | Company Car Mileage |
| COMPU | Computer |
| ENTER | Entertainment |
| FEESD | Fees/Dues |
| GASXX | Gas |
| GOODW | Goodwill |
| GRTRN | Ground Transportation |
| LODGA | Lodging - Track Hotel Spending |
| MEALS | Meal |
| MEETG | Meetings |
| OFFIC | Office |
| OTHER | Other |
| PRCAR | Personal Car - Fixed Expense |
| PRCRM | Personal Car Mileage (Expense Professional), Car Mileage (Expense Standard) |
| PRKNG | Personal Car - Parking Expense |
| RAILX | Rail |
| SHIPG | Shipping |
| SUBSC | Subscription/Publication |
| TELEC | Telecom |
| TRADE | Trade/Convention |
| TRAIN | Training |
AUTHENTICATION
Authentication
Special Note (Please Read First)
If you are an existing partner with an existing app, please read both the Migration to Oauth2 Tokens and Getting Started documentation first. If you have any questions, please contact your Partner Enablement team representative before proceeding.
- Overview
- Tokens
- Types of grants
- Response Codes
- Troubleshooting
Note: The Pre-2017 Authorization (Deprecated) documentation be found here
Access Tokens
The Oauth2 service generates access tokens for authenticated users, applications or companies. The token returned in the Oauth2 response can be used to access protected resources on SAP Concur services.
The Oauth2 response can, depending on grant type contain these values:
| Name | Type | Format | Description |
|---|---|---|---|
expires_in |
string |
- | The lifetime in seconds of the access token |
scope |
string |
- | The scope of the access token as granted to the client application |
token_type |
string |
- | The type of token returned. Value will be Bearer |
access_token |
string |
- | Token used to access protected resources of SAP Concur services. |
refresh_token |
string |
- | Refresh token required to request a new access token for a given user. |
geolocation |
string |
- | The base URL for where the user profile lives. See base URI for usage. |
id_token |
string |
- | The OCID Token in the JSON Web Token (JWT) format that describes the user or company |
Token Response
HTTP/1.1 200 OK
Content-Type: application/json
Date: date-requested
Content-Length: 3397
Connection: Close
{
"expires_in": "3600",
"scope": "app-scopes",
"token_type": "Bearer",
"access_token": "access_token",
"refresh_token": "refresh_token",
"id_token": "ocid_token",
"geolocation": "https://us.api.concursolutions.com"
}
Obtaining a token
You can obtain a token for three different types of principals in the SAP Concur universe.
- User
- Application
- Company
Token Lifetime
An accessToken has a one hour lifetime.
In order to obtain a token, the client application needs to call the Oauth2 endpoint using various grants depending on the authentication scenarios required. The full list of supported scenarios is provided below:
Refreshing a token
The refresh grant is used to refresh an access_token that has expired. This grant can be used anytime a refresh_token is returned in the response of another grant request. No user interaction is required.
Token Lifetime
A refresh token has a six month lifetime. If the refresh token expires, the client application must reinitiate the authorization process. When a refresh token is used to request a new access token, both a new access token as well as a new refresh token are returned in the response. This token can change even if most of the time, this value is the same. Client applications should treat all returned refresh tokens as new tokens and overwrite the stored tokens with the new token from the response.
It is recommended that the client application use the refresh grant to request a new access token as the initial step of accessing protected resources of SAP Concur services.
Refreshing the token
To request a new access token using a valid refresh token, use the Oauth2 /token endpoint. Use the application/x-www-form-urlencoded content type.
POST /oauth2/v0/token
Post Body
| Name | Type | Format | Description |
|---|---|---|---|
client_id |
string |
UUID |
Required The client applications client_id supplied by App Management |
client_secret |
string |
UUID |
Required The client applications client_secret supplied by App Management |
refresh_token |
string |
UUID |
Required An existing valid refresh token to be used to request a new access token |
scope |
string |
- | Optional The client applications list of scopes |
grant_type |
string |
- | Required The grant type instructs the Oauth2 service how to process the request. For refresh token, the value must be refresh_token |
Request
POST /oauth2/v0/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: us.api.concursolutions.com
Connection: close
Content-Length: 437
POST BODY
client_id=your-client_id
&client_secret=your-client_secret
&grant_type=refresh_token
&refresh_token=valid-refresh_token
&scope=app-scope
Response
HTTP/1.1 200 OK
Content-Type: application/json
Date: date-requested
Content-Length: 3397
Connection: Close
{
"expires_in": "3600",
"scope": "app-scopes",
"token_type": "Bearer",
"access_token": "access_token",
"refresh_token": "refresh_token",
"id_token": "ocid_token",
"geolocation": "https://us.api.concursolutions.com"
}
When the token has been refreshed, store the geolocation and the refresh token as they may have changed. On subsequant calls, use the last received golocation and refresh token.
Revoking a token
All refresh_tokens associated to a user for an application can be revoked by calling the https://us.api.concursolutions.com/app-mgmt/v0/connections endpoint with a DELETE action. You have to provide the User's accessToken in the Authorization Header as Authorization: Bearer <access_token>.
DELETE https://us.api.concursolutions.com/app-mgmt/v0/connections
Request
DELETE https://us.api.concursolutions.com/app-mgmt/v0/connections
Authorization: Bearer {token}
Response
HTTP/1.1 200 OK
Managing tokens
Refresh Tokens are strings that allow your application to obtain a fresh accessToken on behalf of a user to access SAP Concur APIs. The exact format of the string can change, but may look similar to the following:
e013335d-b4ce-4c43-a7e4-b67abc1adcb0
It is highly recommended that you store Refresh Tokens together with your user's authorization metadata in your application every time you obtain a new refreshToken as they might change depending on different scenarios.
FOR APP CENTER AND SUPPLIER PARTNERS supporting all geolocations, storing the authorization metadata, including the geolocation are REQUIRED.
Base URIs
When making API calls, the appropriate base URI should be used. There are three different scenarios: 1. Obtaining a token for a user. 2. Refreshing a token. 3. Calling other APIs.
The base URI for obtaining a token will leverage your application's geolocation. The base URI for refreshing tokens and all other API calls will leverage the token's geolocation.
Base URIs for Obtaining a Token
When your application is created, you will be provided with a client ID, secret and geolocation. When obtaining a token, your application should use the base URI for the geolocation in which your application exists.
There are two endpoints for each geolocation - one is the default (used for server-side calls) and the other should be used for client-side calls.
The full list of available token geolocations is available on the Base URIs page.
When obtaining the token, the token's geolocation will be included in the response. The token's geolocation should be stored along with the token. The Developer's app will then be able to make subsequent calls using the token and the correct end points based on the token's GEO location.
Base URIs for All Other Calls
When refreshing a token or when calling any other APIs, the token's geolocation should be used as the base URI.
Note: Client-side calls should use the www- variant of the base URI.
For example: When obtaining a token, if the response was the below:
HTTP/1.1 200 OK
Content-Type: application/json
Date: date-requested
Content-Length: 3397
Connection: Close
{
"expires_in": "3600",
"scope": "app-scopes",
"token_type": "Bearer",
"access_token": "access_token",
"refresh_token": "refresh_token",
"id_token": "ocid_token",
"geolocation": "https://us.api.concursolutions.com"
}
When then calling the receipts API to post a receipt, your request should be made to https://us.api.concursolutions.com (if server side) or https://www-us.api.concursolutions.com (for clients).
ID Token
Authentication service will return an OPENID compatible ID token with every token request. This id_token is primarily used to describe information about a user or a company. You can obtain the userId from this token.
Sample id_token:
{
"aud": "e010e25d-b4ce-4ce3-a7e4-b670cb1adcb0",
"concur.profile": "https://us.api.concursolutions.com/profile/v1/principals/76459ad3-f77b-4d98-a21a-55333c9179f0",
"concur.version": 2,
"concur.type": "user",
"sub": "76459ad3-f77b-4d98-a21a-55333c9179f0",
"iss": "https://us.api.concursolutions.com",
"exp": 1485485529,
"nbf": 1485481929,
"at_hash": "351515a6482f4ee1",
"iat": 1485481929
}
Verifying an id_token
The Authentication service exposes JWKs that can be used to validate the id_token in the form of a JWT. Validating a JWT is described in detail in RFC 7519 - sec 7.2
This is the link to the SAP Concur JSON Web Key for Oauth2. https://www-us.api.concursolutions.com/oauth2/v0/jwks
Authorization grant
The authorization grant is the regular 3-legged oauth2 grant and is defined in detail in RFC6749 sec-4.1. This grant requires the user to explicitly authenticate themselves and authorise the application initiating the grant.
The users must be able to authenticate themselves via an SAP Concur username & password. Users will be challenged to login by an Oauth2 HTML page.
Who should use it * 3rd party "partner" websites - or - * non-SAP Concur Applications - & - * Applications that need explicit user authentication & authorization - & - * Applications that can securely store a code, access_token & refresh_token
Grant details
Note that the grant type must be accessed using the
www-version of the API Gateway in order to avoid certificate issues with some browsers. (ex: https://www-us.api.concursolutions.com instead of https://us.api.concursolutions.com)
GET /oauth2/v0/authorize
| Name | Type | Format | Description |
|---|---|---|---|
client_id |
string |
UUID |
Applications client_id supplied by App Management |
redirect_uri |
string |
- | The redirect URI for your application to continue with the Oauth2 flow |
scope |
string |
- | List of scopes that application is asking for |
response_type |
string |
- | code |
state |
string |
- |
With this grant, the user has two authentication options: 1. Username and password 2. One-time link using a verified email address
With both options, once the user is successfully authenticated and the user authorizes your application, the user will be redirected to the redirect_URI specified in the initial /authorize call with a temporary token appended.
<redirect_uri>?geolocation=<token_geolocation>&code=<token>
If the user is not successfully authenticated or does not authorize the scopes for your application, an error code and description will be appended to the redirect URI. Please refer to the Response Codes section for more information.
Your application must then exchange the temporary token for a long-lived token using the below.
POST /oauth2/v0/token
| Name | Type | Format | Description |
|---|---|---|---|
client_id |
string |
UUID |
Applications client_id supplied by App Management |
client_secret |
string |
UUID |
Applications client_secret supplied by App Management |
redirect_uri |
string |
- | The redirect_uri that is registered for the application |
code |
string |
UUID |
The authorization code provided by Auth |
grant_type |
string |
- | authorization_code |
Password grant
The Password grant can be used when there is a trust relationship between the user and the application. There are two credential types allowed with Password Grant:
- "Password": with this credential type, the application either already has the user's credentials or can obtain the user's credentials by directly interacting with the user.
- "AuthToken": This credential type is used for connections from the App Center. For App Center partners and TripLink suppliers, please refer to the certification documentation for more information.
Post Body
| Name | Type | Format | Description |
|---|---|---|---|
client_id |
string |
UUID |
Applications client_id supplied by App Management |
client_secret |
string |
UUID |
Applications client_secret supplied by App Management |
grant_type |
string |
- | Specify which grant type you expect the oauth2 service to process. for password grant, the value is password |
username |
string |
- | specify the username or userId |
password |
string |
- | specify the user's password |
credtype |
string |
- | The credtype signifies to oauth2 which credential set is being submitted in the request. There are two supported values: authtoken and password. For connections from the App Center, use authtoken. if omitted, oauth2 will assume the type is password. |
Request
POST /oauth2/v0/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: us.api.concursolutions.com
Connection: close
Content-Length: 175
POST BODY
client_id=your-client_id
&client_secret=your-client_secret
&grant_type=password
&username=username
&password=password
Response
HTTP/1.1 200 OK
Content-Type: application/json
Date: date-requested
Content-Length: 3397
Connection: Close
{
"expires_in": "3600",
"scope": "app-scopes",
"token_type": "Bearer",
"access_token": "access_token",
"refresh_token": "refresh_token",
"id_token": "ocid_token",
"geolocation": "https://us.api.concursolutions.com"
}
example bad login
{
"error": "invalid_grant",
"error_description": "Incorrect Credentials. Please Retry",
"code": 5
}
Client Credentials grant
Use the application/x-www-form-urlencoded content type.
POST /oauth2/v0/token
Post Body
| Name | Type | Format | Description |
|---|---|---|---|
client_id |
string |
UUID |
Required Applications client_id supplied by App Management |
client_secret |
string |
UUID |
Required Applications client_secret supplied by App Management |
grant_type |
string |
- | Required Specify which grant type you expect the oauth2 service to process. For client_credentials grant, the value is client_credentials |
Request
POST /oauth2/v0/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: us.api.concursolutions.com
Connection: close
Content-Length: 127
POST BODY
client_id=your-client_id
&client_secret=your-client_secret
&grant_type=client_credentials
Response
HTTP/1.1 200 OK
Content-Type: application/json
Date: date-requested
Content-Length: 1626
Connection: Close
{
"expires_in": "3600",
"scope": "app-scopes",
"token_type": "Bearer",
"access_token": "access_token",
"geolocation": "https://us.api.concursolutions.com"
}
One Time Password grant
The One-time Password grant type leverages email, phone (text messaging), instant messaging and similar systems to provide per user access tokens to client applications. This grant type requires the following steps:
- The calling application calls the OAuth2 service specifying the otp grant type along with required parameters.
- The OAuth2 service generates a one time token which it sends through the messaging mechanism chosen by the application.
- The user retrieves the token and presents it to the application. The means of having this presented to the application is the responsibility of the application.
- The application presents this one-time token to the OAuth2 service via the token endpoint.
Request a one-time token to be sent to the user
Use the application/x-www-form-urlencoded content type.
POST /oauth2/v0/otp
Post Body
| Name | Type | Format | Description |
|---|---|---|---|
client_id |
string |
UUID |
Required The client_id as defined in the SAP Concur application management system. |
client_secret |
string |
UUID |
Required The client_secret as set by the client owner in the SAP Concur application management system. |
channel_handle |
string |
- | Required The location (email address, phone number) where the one time token should be sent. Currently, only email address is valid. |
channel_type |
string |
- | Required The type of messaging system to use. Currently only email is valid |
name |
string |
- | Optional The name of the user that appears in the email. |
company |
string |
- | Optional The company or application name that appears in the email. |
link |
string |
- | Optional The callback URL that appears in the email for users to click to complete the auth flow. |
The calling application code can also append n-number of unique client defined parameters in the URI for the purpose of connecting the one time token to the application when received by the user. The names of these parameters cannot conflict with the API defined parameters.
The following are reserved words and cannot be used as client application defined parameters:
/otp: "client_id" "client_secret" "channel_type" "channel_handle"
/token: "client_id" "client_secret" "channel_type" "channel_handle" "scope" "grant_type" "otp"
If the calling application chooses to send custom parameters, all of these exact same parameters must be included in subsequent API calls to acquire the access token. In other words, the URI signature, modulo the one time token parameter itself and token service specific parameters, must match the originating URI signature.
Request
POST /oauth2/v0/otp HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Accept: application/json
Host: us.api.concursolutions.com
Connection: close
Content-Length: 437
POST BODY
client_id=your-client_id
&client_secret=your-client_secret
&channel_handle=email adress
&channel_type=valid-email
&link=https://example.com/callback
Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 22
Date: date-requested
{
"message": "otp sent"
}
Request an access token
The One Time Password grant requires that all of the parameters, including client application defined parameters to be sent in the request body when requesting an access token. Use the application/x-www-form-urlencoded content type.
POST oauth2/v0/token
Post Body
| Name | Type | Format | Description |
|---|---|---|---|
client_id |
string |
UUID |
Required The client_id as defined in the SAP Concur application management system. |
client_secret |
string |
UUID |
Required The client_secret as set by the client owner in the SAP Concur application management system. |
channel_handle |
string |
- | Required The location (email address, phone number) where the one time token should be sent. |
channel_type |
string |
- | Required The type of messaging system to use. Currently only email is valid |
scope |
string |
- | The scope(s) requested by the client for the token. |
grant_type |
string |
- | Required The grant type being used, specifically for this approach: otp. |
otp |
string |
- | Required The one-time token provided as a result of the Send a one time token to the user method. |
Request
POST /oauth2/v0/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: us.api.concursolutions.com
Connection: close
Content-Length: 437
POST BODY
client_id=your-client_id
&client_secret=your-client_secret
&channel_handle=email adress
&channel_type=valid-email
&scope=app_scope
&grant_type=otp
&otp=one-time-token
Response
HTTP/1.1 200 OK
Date: date-requested
Content-Length: 1490
Connection: keep-alive
{
"expires_in": "3600",
"scope": "app-scopes",
"token_type": "Bearer",
"access_token": "access_token",
"refresh_token": "refresh_token",
"id_token": "ocid_token",
"geolocation": "https://us.api.concursolutions.com"
}
Response Codes
HTTP Status returned by oauth2
| HTTP Status | Description |
|---|---|
| 200 | OK - Successful call, response is in body. |
| 400 | Bad Request (error, error_description, code) |
| 401 | Unauthorized (error, error_description, code) |
| 403 | Forbidden (error, error_description, code) |
| 404 | Not Found (error, error_description, code) |
| 500 | Server Error, error message is in body. |
| 503 | Server Timed Out, error message is in body. |
4xx class errors have a JSON response with the following fields
{
"code": <number>,
"error": <error>,
"error_description": <error_description>,
"geolocation": <geolocation url where user lives>
}
/authorize
If the authorization or authentication are unsuccessful, your application will receive an error code and description at the redirect_uri provided.
error_code=<>
&error_description=<>
In all cases, the friendly error description should be displayed to the user.
/token
| Code | Error | Description |
|---|---|---|
| 5 | invalid_grant |
Incorrect credentials. Please Retry |
| 10 | invalid_grant |
Account is disabled. Please contact support |
| 11 | invalid_grant |
Account is disabled. Please contact support |
| 12 | invalid_grant |
Logon Denied. Please contact support |
| 13 | invalid_grant |
Logon Denied. Please contact support |
| 14 | invalid_grant |
Account Locked. Please contact support |
| 16 | invalid_request |
user lives elsewhere |
| 19 | invalid_grant |
Incorrect credentials. Please Retry |
| 20 | invalid_grant |
Logon Denied. Please contact support (typically due to IP restriction) |
| 51 | invalid_request |
username was not supplied |
| 52 | invalid_request |
password was not supplied |
| 53 | invalid_client |
company is not enabled for this client |
| 54 | invalid_scope |
requested scope exceeds granted scope |
| 55 | invalid_request |
we don't know this email |
| 56 | invalid_request |
otp was not supplied |
| 57 | invalid_request |
channel_type missing |
| 58 | invalid_request |
channel_handle missing |
| 59 | access_denied |
client disabled |
| 60 | invalid_grant |
these are not the grants you are looking for |
| 61 | invalid_client |
client not found |
| 62 | invalid_request |
client_id was not supplied |
| 63 | invalid_request |
client_secret was not supplied |
| 64 | invalid_client |
Incorrect credentials. Please Retry |
| 65 | invalid_request |
grant_type was not supplied |
| 80 | invalid_request |
invalid channel type |
| 81 | invalid_request |
bad channel handle |
| 83 | invalid_request |
otp not found |
| 84 | invalid_request |
fact verification failed |
| 85 | invalid_request |
otp verification failed |
| 100 | invalid_request |
backend does not know about this username |
| 101 | invalid_request |
code was not supplied |
| 102 | invalid_request |
redirect_uri was not supplied |
| 103 | invalid_request |
code is bad or expired |
| 104 | invalid_grant |
redirect_uri does not match the previous grant |
| 105 | invalid_grant |
this grant was not issued to you! |
| 106 | invalid_request |
refresh_token was not supplied |
| 107 | invalid_request |
refresh disallowed for app |
| 108 | invalid_grant |
bad or expired refresh token |
| 109 | invalid_request |
loginid was not supplied |
| 115 | invalid_request |
unauthenticated client will not be issued token! |
| 117 | invalid_request |
nonce is mandatory for this response_type |
| 118 | invalid_request |
display is invalid |
| 119 | invalid_request |
prompt is invalid |
| 119 | invalid_request |
prompt must be set to consent for offline_access |
| 120 | invalid_request |
credtype is invalid |
| 121 | invalid_request |
login_type is invalid |
| 122 | invalid_request |
proxies supplied are invalid |
| 123 | invalid_request |
principal is disabled |
/otp
| Code | Error | Description |
|---|---|---|
| 16 | invalid_request |
user lives elsewhere |
| 57 | invalid_request |
channel_type was not supplied |
| 58 | invalid_request |
channel_handle was not supplied |
| 60 | invalid_grant |
these are not the grants you are looking for |
| 61 | invalid_client |
client_id is not known to us |
| 62 | invalid_request |
client_id was not supplied |
| 63 | invalid_request |
client_secret was not supplied |
| 80 | invalid_request |
invalid channel type |
| 81 | invalid_request |
bad channel handle |
| 82 | invalid_request |
the number of open otp requests has been exceeded |
Troubleshooting
In order to assist with troubleshooting, SAP Concur responds with a unique correlationId in the response header. The key to look for is correlationid. This unique code can be used during troubleshooting as it identifies the API call in the log files. You should record this information in your own API call logs as well so that you can pass this information on to the SAP Concur support team.
Example of the correlationid in the response:
< HTTP/1.1 200 OK
< Server: cnqr-papeete
< Date: Mon, 04 Dec 2017 22:07:05 GMT
< Content-Type: application/json
< Content-Length: 2897
< Connection: keep-alive
< Concur-Correlationid: 2803b8f8-a42b-43c2-a739-b8768e4759b8
Enterprise Business Applications
Only the Password Grant Type is available for obtaining company-level tokens.
- To begin the authentication flow, a Customer's SAP Concur Administrator clicks on the Connect button within the App Center listing and authorizes the partner's app. This app listing is located within customer's SAP Concur system's App Center tab.
- The SAP Concur authorization service will redirect the Admin to the Partner’s Landing Page. Partners should follow the App Center UX Guidelines to create a web page that listens for an HTTP GET request from SAP Concur.
- The redirect URI will contain an id, requestToken and userId parameters. Example:
https://{partner_redirect_URI}?id=8568a4cd-8ffc-49d6-9417-be2d69aa075f&requestToken=5l85ae5a-426f-4d6f-8af4-08648c4b696b&userId=9bdded51-00b8-4f84-8bef-6d3afe727007 - When the Partner application receives the redirect call, the Partner should strip the
idandrequestTokenvalues from the URI and use those on a Post request to the SAP Concur Authorization service to obtain the official Oauth2 Access Token and Refresh Token for the customer using the password grant. As explained in detail in this presentation, the Partner must have Data Center Geo Awareness related to the token. We currently have 3 Data Centers and the API end points change based on these Data Centers so it is imperative the proper token management is followed. Otherwise, your app will not make the correct call per Access token. - An access token is valid for only one hour. The access token should be cached in memory and discarded after use.
- After the Admin has successfully completed the login/enrollment process, the Partner should store the following elements with the customer’s profile metadata.
refresh_token: (36 characters including dashes) Valid for six months from the day and time issued.refresh_expires_in: This is Epoch time format, convert to UTC.geolocation: To be used when making API calls on behalf of the customer.id: Akasub, is the customer’s unique identifier (UUID). It can be retrieved from the following sources:- From the re-direct URI as the id element.
- By decoding the
id_tokenreturned with Access token, as thesubelement. (See https://jwt.io)
- It is highly recommended that Partners log the following elements:
userId: the user who clicked on the Connect button (returned in the re-direct URI)correlationid: SAP Concur responds with a unique code which identifies the API call in the log files. (returned in the response header). More details can be found here.
Learn More About Scopes
Partner Application Scope Usage
The table below lists all the possible scopes that an SAP Concur Partner Application might have access to. Please refer to the App Center Terms and Conditions and look under the "Shared Information" dialogue. Links to API endpoints that are accessible by each scope are mapped out.
Note:
- One scope may have access to more than one API/Endpoint.
- One scope may have both read and write access unless otherwise specified.
- The partner application does not necessarily use all the APIs that are available for a scope.
| Scope | User Description | APIs |
|---|---|---|
| ATTEND | Add, update, or deactivate attendees | Attendees |
| BANK | Employee Banking | Report Details-Employee Banking |
| budgetitem.read | Grants read access to the budget resources | Budget v4 |
| budgetitem.write | Grants read and write access to the budget resources | Budget v4 |
| CCARD | Credit Card | Company Card Transactions, Report Details-Card Transactions |
| COMPD | Company details | Travel Profile v3 Company Details, Travel Profile v2 Custom Fields |
| company.read | Read company profile information | Profile, Company API (Profile v1) |
| company.write | Read and update company profile information | Profile, Company API (Profile v1) |
| CONFIG | Understand how to post expense information according to your company's configuration | Expense Group Configurations, Quick Expense v4 |
| CONREQ | Use your travel profile information to get or update connection requests between SAP Concur and travel reward program partners | Connection Requests 3.2, Connection Requests 3.0, Connection Requests 3.1 |
| EMERG | Emergency Contact information | Travel Profile v2 Emergency Contact |
| events.topic.read | Grants read and write access to Event Topics once subscribed | Event Subscription Service v4 |
| expense.exchangerate.writeonly | Create custom exchange rates | Exchange Rate v4 |
| expense.report.read | Get information about expense reports | Comments v4, Reports v4, Allocations v4, Expenses v4 |
| expense.report.readwrite | Read and write expense report headers | Comments v4, Reports v4, Allocations v4, Expenses v4 |
| expense.report.workflowstatus.write | Approve or Send Back the Report in the workflow | Comments v4, Reports v4 |
| EXPRPT | Get, add, approve, or update expense reports | Allocations v3, Expense Report Entry v2, Expense Report Form Field v1.1, Expense Report Form v1.1, Expense Report Itemization v3, Expense Report Integration Status v2, Expense Report POST Exceptions v1.1, Expense Report POST Submission v1.1, Expense Report POST Workflow v1.1, Expense Reports v3, Expense Report v2, Expense Entry Itemization POST v1.1, Expense Entry Itemization v1.1, Expense Entry v1.1, Expense Entry GET 1.1, Expense Entry POST 1.1, Expense Report Header v1.1, Expense Reports List v1.1, Expense Report v1.1 Report Details, Expense Report v1.1 Locations, Expense Report v1.1 Location, Expense Report v2, Expense Report v2 Reports |
| EXTRCT | Extract expense data | Extracts v1 |
| fiscalcalendar.read | Grants read access to the fiscal calendar | Budget v4 |
| fiscalcalendar.write | Grants read and write access to the fiscal calendar | Budget v4 |
| identity.user.ids.read | Read user ID data | Identity v4 |
| identity.user.core.read | Read user core data | Identity v4 |
| identity.user.coresensitive.read | Read core sensitive data | Identity v4 |
| identity.user.enterprise.read | Read user enterprise data | Identity v4 |
| identity.user.coreenterprise.writeonly | Write access to all core and enterprise fields except externalID | Identity v4 |
| identity.user.externalID.writeonly | Write access to externalID only | Identity v4 |
| IMAGE | Add or get invoice and receipt images | Receipt Image v3, Receipt Image v1 |
| INSGHT | Access itineraries and identify missing trip segments | Insights-Latest Bookings, Insights-Opportunities |
| invoice.providerpayment.write | Read access to pending payments, and write access to payment status | Invoice Pay v4 |
| INVPMT | Create, Retrieve and Update for Payment Requests | Invoice Payment Request v3, Invoice Retrieve Payment Request Digests v3 |
| INVPO | Create or update purchase orders | Invoice Purchase Orders v3 |
| INVTV | View tax invoices and update validation status | Invoice Sales Tax Validation Request v3 |
| INVVEN | Vendors search and retrieve list of vendors | Invoice Vendor v3, Invoice Vendor Group Swagger, Invoice Vendor Bank Swagger |
| ITINER | Get, add, or update travel itineraries and bookings | Itinerary Web Service, Travel-Booking Resource, Itinerary Service, Travel-Trips v1.1, Travel Services, Trip Approval v1 |
| LIST | Use and update drop-down lists configured by your company | List Item v3, List v1, List v1 Resource, Get List of List v1, Post New List v1, Budget v4 |
| locate.location.read | Allows the application to only to view the SAP Concur Locate user location | User Location v4 |
| locate.location.write | Allows the application to write user location information using SAP Concur Locate API service | User Location v4 |
| MEDIC | Medical alerts | Travel Profile v2 Medical Alerts |
| NOTIF | Receive notifications when expense reports change | Event Notification Callout, Get Notification, Delete Notification, Post Notification |
| PASSV | Passport visa information | Travel Profile v2 Passport, Travel Profile v2 Visa |
| PAYBAT | Close and export payment batches | Payment Batches v1.1 |
| purchaserequest.read | Allows you to retrieve purchase requests | Purchase Request v4 |
| purchaserequest.write | Allows you to create new purchase requests | Purchase Request v4 |
| quickexpense.writeonly | Write quick expense | Quick Expense v4 |
| RCTIMG | Add or update receipt and OCR images | Receipt Image v3 |
| receipts.read | Read receipt data | Receipts v4 |
| receipts.write | Read receipt data and post receipts | Receipts v4 |
| receipts.writeonly | Post receipts on your behalf | Receipts v4, Quick Expense v4 |
| spend.list.delete | Delete capabilities for spend lists | List v4 |
| spend.list.read | Read only access to spend list and category details | Reports v4, Allocations v4, Expenses v4, List v4 |
| spend.list.write | Read and write access to spend lists | List v4 |
| spend.listitem.delete | Delete capabilities for spend list items | List Item v4 |
| spend.listitem.read | Read only access to spend list items listItemId | Reports v4, Allocations v4, Expenses v4, List Item v4 |
| spend.listitem.write | Read and write access to spend list items | List Item v4 |
| SUPSVC | Get supplier data | Suppliers v3 |
| TAXINV | Get or validate digital tax invoices | Sales Tax Validation v3 |
| TMCSP | TMC specific information | Travel Profile v2 TMC |
| travelallowance.allowancedays.read | View the allowance days in an expense report | Travel Allowance API |
| travel.receipts.read | Read travel receipt requests | Travel Receipts, Travel Receipts Sample |
| travel.receipts.write | Post travel receipts | Travel Receipts, Travel Receipts Sample |
| travelrequest.write | Add, update, or delete travel requests | Request v4 |
| TSAI | TSA information | Travel Profile v2 TSA |
| TRVPRF | Access and update Concur Travel profile information | Travel Profile v2, Travel Profile v2 Resource |
| TRVPTS | Access user balances and post travel points redemptions | Travel Profile v1 Travel Points |
| TRVREQ | Add, update, or delete authorization requests | Travel Request v3 |
| TWS | Approve or reject travel itineraries | Trip Approvals |
| UNUTX | Unused tickets | Travel Profile v2 Unused Tickets |
| USER | Add or update SAP Concur user accounts | User v1, User v3, User v3.1 |
| user.read | Read profile information | Profile, User API (Profile v1), Comments v4, Reports v4, Allocations v4, Expenses v4, Quick Expense v4 |
| user.write | Read and update profile information | Profile, User API (Profile v1) |
| user_read | Read only access to user travel preference data | User v1, User v3, User v3.1 |
Company Level Authentication
Company
Company is a top-level principal within Concur and you would be able to obtain an access token and a refresh token on a Company's behalf just like you would be able to with a User. Only one authorization flow is currently available for obtaining tokens for a Company, which is the Password grant using a temporary auth token received from the App Center.
Obtaining an auth token
To begin the authentication flow for a company, one must first obtain a temporary auth token through AppCenter's interface. AppCenter will request for a temporary auth token and hand it off to the partner, who will then in turn use Password grant to exchange the temporary auth token for a full access token and refresh token for the company.
Auth tokens are valid only for 12 hours. Partners have 12 hours to exchange the auth token for a refresh and access token, and can use this auth token multiple times within the 12 hours in case of network failure.
This auth flow diagram describes this handshake:
Company Authentication Flow Sequence Diagram

AppCenter will call this endpoint to obtain an authToken.
POST /profile-service/v1/keys/principals/<companyId>/authtoken/
Sample Curl:
curl -E appcenter.p12:. -H 'concur-correlationid: githbuwiki' -XPOST https://us.api.concursolutions.com/profile-service/v1/keys/principals/08BCCA1E-0D4F-4261-9F1B-F778D96617D6/authtoken/
200 OK
{
"status": "PASS",
"code": 0,
"errormsg": "",
"token": "<authToken>"
}
AppCenter redirects User to Client's auth handler URI (Connect URL) and passing in the authToken
301 Redirect https://client.app.url?id=$company_uuid&requestToken=$request_token&userID=$user_uuid
At this point, the user should be prompted to sign in to your application. If the user doesn't not have account, the user should have the ability to create one. For applications that have user read scope, the User UUID can be used to pre-populate the account creation forms. Please see the App Center User Experience guidelines for more information.
Client app calls Oauth2 password grant to get an access token for the company
| Name | Type | Format | Description |
|---|---|---|---|
client_id |
string |
UIID |
Applications client_id supplied by App Management |
client_secret |
string |
UUID |
Applications client_secret supplied by App Management |
grant_type |
string |
- | Specify which grant type you expect the oauth2 service to process. For password grant, the value is password |
username |
string |
- | specify the companyId to be used in the password grant request. The id above. |
password |
string |
- | specify the authToken to be used in the password grant request. The requestToken above. |
credtype |
string |
- | The credtype signifies to oauth2 which credential set is being submitted in the request. The value: authtoken. |
Example
Request
POST /oauth2/v0/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: us.api.concursolutions.com
Connection: close
Content-Length: 175
client_id=your-client_id
&client_secret=your-client_secret
&grant_type=password
&username=<companyId>
&password=<authtoken>
&credtype=authtoken
Response
Success
HTTP/1.1 200 OK
Content-Type: application/json
Date: date-requested
Content-Length: 3397
Connection: Close
{
"expires_in": "3600",
"scope": "app_scopes",
"token_type": "Bearer",
"access_token": "access_token",
"refresh_token": "refresh_token",
"geolocation":"https://us.api.concursolutions.com"
}
Failure
{
"error": "invalid_grant",
"error_description": "Incorrect Credentials. Please Retry",
"code": 5
}
Response Codes
HTTP Status Code returned by oauth2
| HTTP Status Code | Description |
|---|---|
| 200 | OK - Successful call, response is in body. |
| 400 | Bad Request (error, error_description, code) |
| 401 | Unauthorized (error, error_description, code) |
| 403 | Forbidden (error, error_description, code) |
| 404 | Not Found (error, error_description, code) |
| 500 | Server Error, error message is in body. |
| 503 | Server Timed Out, error message is in body. |
4xx class errors have a JSON response with the following fields
{
"code": "<number>",
"error": "<error>",
"error_description": "<error_description>"
}
/token
| Code | Error | Description |
|---|---|---|
| 5 | invalid_grant |
Incorrect credentials. Please Retry |
| 10 | invalid_grant |
Account is disabled. Please contact support |
| 11 | invalid_grant |
Account is disabled. Please contact support |
| 12 | invalid_grant |
Logon Denied. Please contact support |
| 13 | invalid_grant |
Logon Denied. Please contact support |
| 14 | invalid_grant |
Account Locked. Please contact support |
| 16 | invalid_request |
user lives elsewhere |
| 19 | invalid_grant |
Incorrect credentials. Please Retry |
| 51 | invalid_request |
username was not supplied |
| 52 | invalid_request |
password was not supplied |
| 53 | invalid_client |
company is not enabled for this client |
| 54 | invalid_scope |
requested scope exceeds granted scope |
| 55 | invalid_request |
we don't know this email |
| 56 | invalid_request |
otp was not supplied |
| 57 | invalid_request |
channel_type missing |
| 58 | invalid_request |
channel_handle missing |
| 59 | access_denied |
client disabled |
| 60 | invalid_grant |
these are not the grants you are looking for |
| 61 | invalid_client |
client not found |
| 62 | invalid_request |
client_id was not supplied |
| 63 | invalid_request |
client_secret was not supplied |
| 64 | invalid_client |
Incorrect credentials. Please Retry |
| 65 | invalid_request |
grant_type was not supplied |
| 80 | invalid_request |
invalid channel type |
| 81 | invalid_request |
bad channel handle |
| 83 | invalid_request |
otp not found |
| 84 | invalid_request |
fact verification failed |
| 85 | invalid_request |
otp verification failed |
| 100 | invalid_request |
backend does not know about this username |
| 101 | invalid_request |
code was not supplied |
| 102 | invalid_request |
redirect_uri was not supplied |
| 103 | invalid_request |
code is bad or expired |
| 104 | invalid_grant |
redirect_uri does not match the previous grant |
| 105 | invalid_grant |
this grant was not issued to you! |
| 106 | invalid_request |
refresh_token was not supplied |
| 107 | invalid_request |
refresh disallowed for app |
| 108 | invalid_grant |
bad or expired refresh token |
| 109 | invalid_request |
loginid was not supplied |
| 115 | invalid_request |
unauthenticated client will not be issued token! |
| 117 | invalid_request |
nonce is mandatory for this response_type |
| 118 | invalid_request |
display is invalid |
| 119 | invalid_request |
prompt is invalid |
| 119 | invalid_request |
prompt must be set to consent for offline_access |
GET Users Bulk API
This API has been deprecated for the US and EMEA data centers.
Deprecation Date: 6/30/2021
Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.
Learn more in the API Lifecycle & Deprecation Policy.
Obtain Company Token
Company is a top-level principal within SAP Concur and you would be able to obtain an access token and a refresh token on a company's behalf just like you would be able to with a user. Only one authorization flow is currently available for obtaining tokens for a company, which is the Password grant.
For more information and instructions for obtaining a Company Token, please review the Company Level Authentication
Calling Users Bulk API
This endpoint will retrieve a list of users that belong to a company and return basic company information together with the list of users.
Request
URI
Template
GET /users/
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
total |
string |
- | The total number of users within the company. |
offset |
string |
- | The offset to begin returning the list of users. |
limit |
string |
- | The number of user records to return in that call. Maximum: 1000 |
<name_of_filter> |
string |
- | Filters results based on the desired field. Supported values: isactive, loginid, lastname, employeeid, primaryemail, countrycode, id |
Example
Request
GET /users HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: us.api.concursolutions.com
Sample Curl:
curl -v -X GET -H "Authorization: Bearer $token" \
-H "Accept: application/json" \
'https://us.api.concursolutions.com/users/?offset=0&limit=100&isactive=true'
Response
200 OK
{
"total": 2,
"offset": 0,
"limit": 100,
"company": {
"name": "Company Name LLC",
"address": "601 108th ave NE",
"city": "Bellevue",
"state": "WA",
"zip": "98004",
"country": "US"
},
"Items": [
{
"Active": true,
"CountryCode": "US",
"CellPhoneNumber": "5551234567",
"PrimaryEmail": "johndoe@gmail.com",
"EmployeeID": "johndoe@gmail.com",
"ID": "99BFFFC3-C0BE-44FF-A441-AE1FFFFFF75B8",
"Emails": ["PrimaryEmail", "VerifiedEmail", "email2", "email3", "email4", "email5"],
"OrganizationUnit": null,
"MiddleName": "",
"LastName": "Doe",
"FirstName": "John",
"LoginID": "johndoe@gmail.com"
},
{
"Active": true,
"CountryCode": "US",
"CellPhoneNumber": null,
"PrimaryEmail": "janedoe@gmail.com",
"EmployeeID": "janedoe@gmail.com",
"ID": "55FFF504-C7B8-49FF-9E15-6248FFFFFCDB",
"Emails": ["PrimaryEmail", "VerifiedEmail", "email2", "email3", "email4", "email5"],
"OrganizationUnit": null,
"MiddleName": "",
"LastName": "Doe",
"FirstName": "Jane",
"LoginID": "janedoe@gmail.com"
}
]
}
Schema
| Property Name | Type | Format | Description |
|---|---|---|---|
Items |
array |
User |
Required Contains the Client, Users, Locations, Source Partner and Transaction. |
NextPage |
string |
- | The URI of the next page of results, if any. |
User
| Property Name | Type | Format | Description |
|---|---|---|---|
Active |
boolean |
- | Indicates whether the user is currently active or not. |
CellPhoneNumber |
string |
- | The cell phone number of the user. |
EmployeeID |
string |
- | The employee ID of the user. |
FirstName |
string |
- | The first name of the user. |
ID |
string |
- | The unique identifier of the resource. |
LastName |
string |
- | The last name of the user. |
LoginID |
string |
- | The login ID of the user. |
MiddleName |
string |
- | The middle name of the user. |
OrginzationUnit |
string |
- | The organization unit of the user. |
PrimaryEmail |
string |
- | The primary email of the user. |
URI |
string |
- | The URI to the resource. |
OAuth2 - Getting Started
The SAP Concur new Oauth2 framework is a very simple way to implement a Unified Token Authentication mechanism within your application. Here is a four step guide to helping you get up to speed and making calls to a SAP Concur API.
Note: The Pre-2017 Authorization (Deprecated) documentation can be found here
- Obtain Your Application clientID and clientSecret
- Obtaining an Access Token
- Calling an API with the Access Token
- Access Token Expiry and Obtaining a Fresh One
1. Obtain Your Application clientID and clientSecret
Before you can obtain an accessToken, you need to register an application with SAP Concur. You can do this by contacting your Partner Enablement Manager or Partner Account Manager. Once you have registered an application, you will receive a clientId, clientSecret and geolocation. The clientId is a unique UUID4 identifier for your application, and the clientSecret is your application's password. You will be using this credential to obtain tokens either for the application itself, or on behalf of a user. The geolocation is your default base URI for initiating all new connections.
2. Obtaining an Access Token
In order for an application to call a SAP Concur API, you need to obtain an accessToken on behalf of either a User, Company or Application. There are multiple ways of obtaining an accessToken through the various grants (Password, Authorization, Client Credentials, One-time Password) .
This section provides a quick start guide for generating an access token. If you are developing an application to be certified for the App Center or as a TripLink supplier, please refer to the certification documentation for the grant types your application must support.
For simplicity, we will use the Password grant flow as an example. The Password grant flow is used when you need to authenticate a user, using its username and password. This is typically reserved from SAP Concur applications (i.e. where the user's credentials will be captured and stored) but is used here for demonstration purposes.
When making the call, you will use your app's geolocation as the base URI followed by the endpoint. For example, if your geolocation is https://us.api.concursolutions.com, you will call https://us.api.concursolutions.com/oauth2/v0/token.
The first time you request for an accessToken a refreshToken is also returned. There are certain conditions where a refreshToken is not returned. This is used to get a new accessToken when one has expired. (see below for more info)
Example shell script using cURL to obtain an accessToken:
oauth2_base=https://us.api.concursolutions.com/oauth2
username=<concur_username> eg. john.doe@gmail.com
password=<password> eg. password1
client_id=<clientId> eg. e01f725d-b4ce-4ce3-a664-b670cb5876cb0
client_secret=<clientSecret> eg. 35c3bd92-fcb8-405e-a886-47ff3fba5664
curl -X POST -H 'concur-correlationid: nameofapp' "$oauth2_base/v0/token" --data "username=$username&password=$password&grant_type=password&client_secret=$client_secret&client_id=$client_id"
Full docs: https://developer.concur.com/api-reference/authentication/apidoc.html#password_grant
Store the token and geolocation.
3. Calling an API with the Access Token
Once you have the accessToken, you need to supply this in an Authorization header in the form of Authorization: Bearer <accessToken> when making a HTTPS call. The accessToken is a large string that looks something like this:
eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IjE0NTU2MTQzNDYifQ.eyJhdWQiOiIqIiwic3ViIjoiaHR0cDovL21zcGNzcHJzcnFhLmNvbmN1ci5jb25jdXJ0ZWNoLm9yZzozMDAzL3Byb2ZpbGUtc2VydmljZS92MS91c2Vycy83NjAwOUFEMy1GNzdCLTREOTgtQTIxQS01NTNDOUM5MTc5RjAiLCJpc3MiOiJodHRwczovL2NvbmN1ci5jb20iLCJleHAiOjE0NzM4OTUxMjksImxlZ2FjeV9hcHBsaWNhdGlvbl9pZCI6MTUwMDA2MzY1OSwidXNlclVSSSI6Imh0dHA6Ly9tc3Bjc3Byc3JxYS5jb25jdXIuY29uY3VydGVjaC5vcmc6MzAwMy9wcm9maWxlLXNlcnZpY2UvdjEvdXNlcnMvNzYwMDlBRDMtRjc3Qi00RDk4LUEyMUEtNTUzQzlDOTE3OUYwIiwidXNlcnV1aWQiOiI3NjAwOUFEMy1GNzdCLTREOTgtQTIxQS01NTNDOUM5MTc5RjAiLCJuYmYiOjE0NzM4OTE1MjksImh0dHBzOi8vYXBpLmNvbmN1cnNvbHV0aW9ucy5jb20vYXBwIjoiaHR0cHM6Ly9hcGkuY29uY3Vyc29sdXRpb25zLmNvbS9hcHAtbWdtdC92MC9hcHBzL2UwMTBlMjVkLWI0Y2UtNGNlMy1hN2U0LWI2NzBjYjFhZGNiMCIsImh0dHBzOi8vYXBpLmNvbmN1cnNvbHV0aW9ucy5jb20vc2NvcGVzIjpbIkNDQVJEIiwiQ09NUEQiLCJVU0VSIiwidXNlcl9yZWFkIiwiRU1FUkciLCJKT0JMT0ciLCJFUkVDUFQiLCJJVElORVIiLCJGSVNWQyIsIkxJU1QiLCJQQVNTViIsIkNPTkZJRyIsIkZPUCIsIkdIT1NUIiwiQ09OUkVRIiwiVFJJUElUIiwiQ09NUEFOWSIsInByb2ZpbGUiLCJFVlMiLCJlbWFpbCIsIlRSVlBUUyIsIkFUVEVORCIsIklOVlBPIiwiTk9USUYiLCJUUlZSRVEiLCJTVVBTVkMiLCJFWFBSUFQiLCJhZGRyZXNzIiwiRVhUUkNUIiwiUEFZQkFUIiwid3Jvbmdfc2NvcGUiLCJJTlZQTVQiLCJJTUFHRSIsIlRBWElOViIsIlJDVElNRyIsIlVOVVRYIiwiVFdTIiwiVE1DU1AiLCJCQU5LIiwiSU5WVkVOIiwib3BlbmlkIiwiTVRORyIsIklOU0dIVCIsIlRSVlBSRiIsIklOVlRWIiwiTUVESUMiLCJUU0FJIl0sImlhdCI6MTQ3Mzg5MTUyOX0.QHY4Mc5A3J981-HDv7KUdgS4tUI-qnmQAxwe9J6DHxuMmYSoGEYZ0dsnLnqc2lO2iVJK6Pg3EBZTArq8_vzV2FK7tA4-IT1eCEHo1e-RWZyWLnR7P56SvZozXpY73daovSH7572HrUm21FXcyLmdaLZyo2LfFcChaghbSCjm1Jg1duH-pLPUW4d89-_pdakmyxfV3GCm2N_XQXoRhNYAAiZcG8UfxEn3TpMHJ96F2n6keJanT_Sn2Sek_sH2EmeeCpg5-jDe0fvLvr1-gY5t0ifq8QBKWHSUUIrGbQvseD6CGzfyiFUqVypN2lukfWACR-26otN50c0OzY6kgY06RA
When you receive the accessToken, store it with the token's geolocation. That geolocation will be the base URI for all subsequent calls.
Armed with the accessToken you can start making calls to an SAP Concur API. Here's an example to retrieve profile information for a User in the Production environment using cURL (utilize the appropriate base URI geolocation for the token). Base URIs Reference:
curl -k -v -H "Accept: application/json" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IjE0NTU2MTQzNDYifQ.eyJhdWQiOiIqIiwic3ViIjoiaHR0cDovL21zcGNzcHJzcnFhLmNvbmN1ci5jb25jdXJ0ZWNoLm9yZzozMDAzL3Byb2ZpbGUtc2VydmljZS92MS91c2Vycy83NjAwOUFEMy1GNzdCLTREOTgtQTIxQS01NTNDOUM5MTc5RjAiLCJpc3MiOiJodHRwczovL2NvbmN1ci5jb20iLCJleHAiOjE0NzM4OTUxMjksImxlZ2FjeV9hcHBsaWNhdGlvbl9pZCI6MTUwMDA2MzY1OSwidXNlclVSSSI6Imh0dHA6Ly9tc3Bjc3Byc3JxYS5jb25jdXIuY29uY3VydGVjaC5vcmc6MzAwMy9wcm9maWxlLXNlcnZpY2UvdjEvdXNlcnMvNzYwMDlBRDMtRjc3Qi00RDk4LUEyMUEtNTUzQzlDOTE3OUYwIiwidXNlcnV1aWQiOiI3NjAwOUFEMy1GNzdCLTREOTgtQTIxQS01NTNDOUM5MTc5RjAiLCJuYmYiOjE0NzM4OTE1MjksImh0dHBzOi8vYXBpLmNvbmN1cnNvbHV0aW9ucy5jb20vYXBwIjoiaHR0cHM6Ly9hcGkuY29uY3Vyc29sdXRpb25zLmNvbS9hcHAtbWdtdC92MC9hcHBzL2UwMTBlMjVkLWI0Y2UtNGNlMy1hN2U0LWI2NzBjYjFhZGNiMCIsImh0dHBzOi8vYXBpLmNvbmN1cnNvbHV0aW9ucy5jb20vc2NvcGVzIjpbIkNDQVJEIiwiQ09NUEQiLCJVU0VSIiwidXNlcl9yZWFkIiwiRU1FUkciLCJKT0JMT0ciLCJFUkVDUFQiLCJJVElORVIiLCJGSVNWQyIsIkxJU1QiLCJQQVNTViIsIkNPTkZJRyIsIkZPUCIsIkdIT1NUIiwiQ09OUkVRIiwiVFJJUElUIiwiQ09NUEFOWSIsInByb2ZpbGUiLCJFVlMiLCJlbWFpbCIsIlRSVlBUUyIsIkFUVEVORCIsIklOVlBPIiwiTk9USUYiLCJUUlZSRVEiLCJTVVBTVkMiLCJFWFBSUFQiLCJhZGRyZXNzIiwiRVhUUkNUIiwiUEFZQkFUIiwid3Jvbmdfc2NvcGUiLCJJTlZQTVQiLCJJTUFHRSIsIlRBWElOViIsIlJDVElNRyIsIlVOVVRYIiwiVFdTIiwiVE1DU1AiLCJCQU5LIiwiSU5WVkVOIiwib3BlbmlkIiwiTVRORyIsIklOU0dIVCIsIlRSVlBSRiIsIklOVlRWIiwiTUVESUMiLCJUU0FJIl0sImlhdCI6MTQ3Mzg5MTUyOX0.QHY4Mc5A3J981-HDv7KUdgS4tUI-qnmQAxwe9J6DHxuMmYSoGEYZ0dsnLnqc2lO2iVJK6Pg3EBZTArq8_vzV2FK7tA4-IT1eCEHo1e-RWZyWLnR7P56SvZozXpY73daovSH7572HrUm21FXcyLmdaLZyo2LfFcChaghbSCjm1Jg1duH-pLPUW4d89-_pdakmyxfV3GCm2N_XQXoRhNYAAiZcG8UfxEn3TpMHJ96F2n6keJanT_Sn2Sek_sH2EmeeCpg5-jDe0fvLvr1-gY5t0ifq8QBKWHSUUIrGbQvseD6CGzfyiFUqVypN2lukfWACR-26otN50c0OzY6kgY06RA" \
https://us.api.concursolutions.com/profile/v1/me
and the response will look like:
{
"addresses": [
{
"type": "Home",
"streetAddress": "",
"locality": "",
"region": "",
"postalCode": "",
"country": "US"
},
{
"type": "Work",
"streetAddress": "",
"locality": "",
"region": "",
"postalCode": "",
"country": "US"
}
],
"travelIds": {
"userId": 85663431,
"companyId": "63E447F6-A6A7-4B70-A951-10F45d693B43",
"companyInternalId": 222458,
"setId": 91157361,
"ruleClassId": 394103,
"travelConfigId": 0
},
"meta": {
"created": "2016-06-08T00:00:00.000",
"lastModified": "2016-08-22T14:32:00.000",
"resourceType": "EnterpriseUser"
},
"displayName": "Brown",
"name": {
"formatted": "Brown, Terry ",
"familyName": "Brown",
"givenName": "Terry",
"middleName": "",
"honorificPrefix": "",
"honorificSuffix": ""
},
"phoneNumbers": [
{
"type": "Home",
"value": "tel:+1-4251231244",
"primary": false,
"notifications": false,
"countryCode": "US",
"countryISDCode": "1"
},
{
"type": "Work",
"value": "tel:+1-4251231234;ext=",
"primary": false,
"notifications": false,
"countryCode": "US",
"countryISDCode": "1"
}
],
"com:concur:Employee:1.0": {
"employeeId": "brown@brown-sandbox.com",
"jobTitle": "",
"managerId": null,
"orgUnitId": null
},
"dateOfBirth": null,
"schemas": [
"com:concur:User:1.0",
"com:concur:Employee:1.0"
],
"active": true,
"id": "e01f725d-b4ce-4ce3-a664-b670cb5876cb0",
"com:concur:TravelPreferences:1.0": {
"air": {
"seat": {
"interrowPosition": null,
"sectionPosition": null
},
"meal": "DontCare",
"homeAirport": null
},
"rail": {
"space": "DontCare",
"meal": "DontCare",
"bedCategory": "DontCare",
"fareSpaceComfort": "DontCare",
"deck": "DontCare",
"coach": "DontCare",
"bed": "DontCare",
"berth": "DontCare",
"noiseComfort": "DontCare",
"contingency": "DontCare",
"seat": "DontCare"
},
"car": {
"smoking": "DontCare",
"carType": "DontCare",
"transmission": "DontCare",
"gpsEnabled": false,
"skirack": false
},
"hotel": {
"earlyCheckin": false,
"remark": null,
"pool": false,
"roomService": false,
"foamPillows": false,
"accessForBlind": false,
"accessForWheelchair": false,
"gym": false,
"roomType": "DontCare",
"restaurant": false,
"rollawayBed": false,
"smoking": "DontCare",
"crib": false
}
},
"gender": null,
"emails": [
{
"value": "brown@brown-sandbox.com",
"type": "Business",
"notifications": true
}
],
"userType": "Enterprise"
}
Full docs: https://developer.concur.com/api-reference/user/
4. Access Token Expiry and Obtaining a Fresh One
Access Tokens have a default One hour lifetime. In order to obtain a fresh accessToken you need to call the auth endpoint using the Refresh Grant. This will return a brand new accessToken and a refreshToken. Refresh Tokens have a default 6 month lifetime. Clients will typically store the refreshToken together with the other user metadata like login information and unique identifiers.
Utilizing the geolocation for the token, here's an example of a cURL call to obtain a new accessToken
curl -X POST 'https://us.api.concursolutions.com/oauth2/v0/token' --data "client_id=$client_id&client_secret=$client_secret&grant_type=refresh_token&refresh_token=<old refresh token>"
Full docs: https://developer.concur.com/api-reference/authentication/apidoc.html#refresh_token
Now that you've made your first call, read up more about the SAP Concur APIs and how they can enhance your application or solve your business needs.
ref: https://developer.concur.com/api-reference/index.html
Migrating old tokens to new Oauth2 Bearer Tokens
Existing applications that use the Pre-2017 Authorization (Deprecated) framework need to move to support the new Oauth2 Bearer Tokens. Applications will need to migrate their existing users who already have connected to it to obtain new Oauth2 tokens without requiring users to reauthorize. This can be done by exchanging an old access token for a new refresh token.
Base URIs
When making API calls, the appropriate base URI for the user's geolocation should be used. See the Base URIs page for the full list.
Exchanging a Token
In order to support new Oauth2, applications need to exchange old access token for new accessToken and refreshToken pair. Once obtained, applications should store these refreshTokens as part of users authorization data.
The new Oauth2 accessToken has a one hour lifetime. Once expired, applications would need to call Oauth2's /v0/token endpoint using a refresh_grant, passing in the user's refreshtoken to obtain a fresh accessToken.
This is significantly different from how the deprecated /net2/Oauth2's method of handling access tokens. Partner's would have to store the new Oauth2 refreshToken instead of the old access token. Before making a call to any of the new v4 APIs, it is advisable to request for a new accessToken before making the API call.
Step 1: Obtain Application Token
Clients can exchange OLD tokens for NEW Oauth2 tokens by calling the exchangeRefreshToken/me endpoint. In order to call this endpoint, you would first need to obtain an Application Token by calling the /v0/token endpoint with the client_credentials grant.
The endpoint also supports a parameter called "returnType=companyToken" This parameter allows a partner who already has what is known as a "WSAdmin" token for a client, to exchange that token for a Company level refresh token.
Step 2: Call exchangeRefreshToken
POST /appmgmt/v0/legacyApps/{OLDConsumerKey}/exchangeRefreshToken/me
If you are exchanging a WSAdmin token for a new Company level refresh token:
POST /appmgmt/v0/legacyApps/{OLDConsumerKey}/exchangeRefreshToken/me?returnType=companyToken
Request Header
| Name | Type | Format | Description |
|---|---|---|---|
Authorization |
string |
Bearer <accessToken> |
Required The NEW client_credentials accessToken. |
Request Body
| Name | Type | Format | Description |
|---|---|---|---|
token |
string |
Required The OLD refreshToken | |
secret |
string |
Required The NEW application client_secret |
Sample Curl:
curl -H 'Authorization: Bearer <accessToken>' -d '{"token": "1_oaCof444CaiNXg1FFG$Perr19qIo", "secret": "12345"}' -X POST https://us.api.concursolutions.com/appmgmt/v0/legacyApps/Bwu0mvTHtKYAnBb3Pgu9AW/exchangeRefreshToken/me
successful call, responds with
200 OK
{
"token": "8c844478-745c-4c45-adf7-1e2777a50dbf",
"created": 1479407196809,
"expired": 1494959196809,
"scopes": [
"EXPRPT",
"LIST",
"BANK",
"CCARD"
],
"context": "{\"userid\":\"7934467f-dcd1-4631-ba34-3ebd28343e8f\",\"cid\":\"3a55c75e-ac1e-4515-845c-0a4978452828\",\"ptype\":\"user\",\"userURI\":\"https://us.api.concursolutions.com/profile-service/v1/users/7934467f-dcd1-4631-ba34-3ebd28343e8f\",\"scope\":\"EXPRPT LIST BANK CCARD\"}"
}
Sample Curl for WSAdmin token exchange for Company level refreh token:
curl -H 'Authorization: Bearer <accessToken>' -d '{"token": "1_oaCof444CaiNXg1FFG$Perr19qIo", "secret": "12345"}' -X POST https://us.api.concursolutions.com/appmgmt/v0/legacyApps/Bwu0mvTHtKYAnBb3Pgu9AW/exchangeRefreshToken/me?returnType=companyToken
successful call, responds with
200 OK
{
"token": "8c844478-745c-4c45-adf7-1e2777a50dbf",
"created": 1479407196809,
"expired": 1494959196809,
"scopes": [
"EXPRPT",
"LIST",
"BANK",
"CCARD"
],
"context": "{\"userid\":\"7934467f-dcd1-4631-ba34-3ebd28343e8f\",\"cid\":\"3a55c75e-ac1e-4515-845c-0a4978452828\",\"ptype\":\"company\",\"userURI\":\"https://us.api.concursolutions.com/profile-service/v1/users/7934467f-dcd1-4631-ba34-3ebd28343e8f\",\"scope\":\"EXPRPT LIST BANK CCARD\"}"
}
Step 3: Obtain New Access Token
Once you have the NEW refreshToken from the response (8c844478-745c-4c45-adf7-1e2777a50dbf) you can then proceed to call /v0/token using the refresh grant to obtain a NEW Oauth2 accessToken.
Sample Curl:
curl -X POST 'https://us.api.concursolutions.com/oauth2/v0/token' -d 'client_id=3a55c75e-ac1e-4515-845c-0a4978452828&client_secret=12345&grant_type=refresh_token&refresh_token=8c844478-745c-4c45-adf7-1e2777a50dbf'
successful call, responds with:
200 OK
{
"expires_in": 3600,
"scope": "EXPRPT LIST BANK CCARD",
"token_type": "Bearer",
"access_token": "eyJ0...demo...eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IjE0NTU2MTQzNDYifQ.eyJjb25jdXIuc2NvcGVzIjpbIkVYUFJQVCIsIkxJU1QiLCJCQU5LIiwiQ0NBUkQiXSwiYXVkIjoiKiIsImNvbmN1ci5wcm9maWxlIjoiaHR0cHM6Ly91cy1ycWEzLmFwaS5jb25jdXJzb2x1dGlvbnMuY29tL3Byb2ZpbGUvdjEvcHJpY2lwYWxzLzc5NmI0NjdmLWRjZDEtNDYzMS1iYTg1LTNlYmQyOGIzNmU4ZiIsImNvbmN1ci52ZXJzaW9uIjoyLCJjb25jdXIudHlwZSI6InVzZXIiLCJjb25jdXIuYXBwIjoiaHR0cHM6Ly91cy1ycWEzLmFwaS5jb25jdXJzb2x1dGlvbnMuY29tL3Byb2ZpbGUvdjEvYXBwcy9lMDEwZTI1ZC1iNGNlLTRjZTMtYTdlNiLCJzdWIiOiI3OTZiNDY3Zi1kY2QxLTQ2MzEtYmE4NS0zZWJkMjhiMzZlOGYiLCJpc3MiOiJodHRwczovL3VzLXJxYTMuYXBpLmNvbmN1cnNvbHV0aW9ucy5jb20iLCJleHAiOjE0Nzk0MTU4NjksImxlZ2FjeV9hcHBsaWNhdGlvbl9pZCI6MTUwMDA2MzY1OSwidXNlclVSSSI6Imh0dHBzOi8vdXMtcnFhMy5hcGkuY29uY3Vyc29sdXRpb25zLmNvbS9wcm9maWxlLXNlcnZpY2UvdjEvdXNlcnMvNzk2YjQ2N2YtZGNkMS00NjMxLWJhODUtM2ViZDI4YjM2ZThmIiwidXNlcnV1aWQiOiI3OTZiNDY3Zi1kY2QxLTQ2MzEtYmE4NS0zZWJkMjhiMzZlOGYiLCJuYmYiOjE0Nzk0MTIyNjksImh0dHBzOi8vYXBpLmNvbmN1cnNvbHV0aW9ucyiaHR0cHM6Ly91cy1ycWEzLmFwaS5jb25jdXJzb2x1dGlvbnMuY29tL3Byb2ZpbGUvdjEvYXBwcy9lMDEwZTI1ZC1iNGNlLTRjZTMtYTdlNC1iNjcwY2IxYWRjYjAiLCJodHRwczovL2FwaS5jb25jdXJzb2x1dGlvbnMuY29tL3Njb3BlcyI6WyJFWFBSUFQiLCJMSVNUIiwiQkFOSyIsIkNDQVJEIl0sImlhdCI6MTQ3OTQxMjI2OX0.I4EeqKZbpfFonitGBZnLBb20NwMjZNNp5e1d3-BRsepEcJSVCVYIV9HAB2EkkopvoLJsAittiZgD0iDwuh2WVgUt_c4QGzNc_-rXRtCIeKyPQRvxUZNQ7y5RTqEQFNo7hrtXiNZ-yV30zlbijP-12XU5Cu4n2VXgRKxvcCUr5j0RcovUc6O0aOR7VTzj4ZbiDdijOEtmKWGluAYyfIlz8XF2aErAB5Jff2fr9UvgHgtbleYV7eBSesvd9hJEk4S-OAtmFoJwLDECLtLcBKyeHnPEe7LmkLYShcflWG2_tYk4ysPIMG6ne5kRNxJKsDbkMItjpXhujBEGi7YIPWtFWQ",
"refresh_token": "31456dcd-b46a-4292-b2d3-f97033338487",
"geolocation": "https://us.api.concursolutions.com"
}
Response Codes
HTTP Status returned by exchangeAccessToken
| HTTP Status | Description |
|---|---|
| 200 | OK - Successful call, response is in body. |
| 400 | Bad Request - see list of responses below. |
| 404 | Not Found |
| 500 | Server Error, error message is in body. |
| 503 | Server Timed Out, error message is in body. |
exchangeAccessToken Response Codes
| CODE | Description |
|---|---|
| OK | OK - Successful call, response is in body. |
| INVALIDSCOPES | One or more scopes requested are not a subset of the allowed scopes. |
| INVALIDAPP | Application is invalid |
| INVALIDTOKEN | Bad or expired token |
| UNAUTHORIZED | Invalid credentials |
HTTP Status returned by oauth2
| HTTP Status | Description |
|---|---|
| 200 | OK - Successful call, response is in body. |
| 400 | Bad Request (error, error_description, code) |
| 401 | Unauthorized (error, error_description, code) |
| 403 | Forbidden (error, error_description, code) |
| 404 | Not Found (error, error_description, code) |
| 500 | Server Error, error message is in body. |
| 503 | Server Timed Out, error message is in body. |
4xx class errors have a JSON response with the following fields
{
"code": <number>,
"error": <error>,
"error_description": <error_description>
}
/token
| Code | Error | Description |
|---|---|---|
| 5 | invalid_grant |
Incorrect credentials. Please Retry |
| 10 | invalid_grant |
Account is disabled. Please contact support |
| 11 | invalid_grant |
Account is disabled. Please contact support |
| 12 | invalid_grant |
Logon Denied. Please contact support |
| 13 | invalid_grant |
Logon Denied. Please contact support |
| 14 | invalid_grant |
Account Locked. Please contact support |
| 16 | invalid_request |
user lives elsewhere |
| 19 | invalid_grant |
Incorrect credentials. Please Retry |
| 51 | invalid_request |
username was not supplied |
| 52 | invalid_request |
password was not supplied |
| 53 | invalid_client |
company is not enabled for this client |
| 54 | invalid_scope |
requested scope exceeds granted scope |
| 55 | invalid_request |
we don't know this email |
| 56 | invalid_request |
otp was not supplied |
| 57 | invalid_request |
channel_type missing |
| 58 | invalid_request |
channel_handle missing |
| 59 | access_denied |
client disabled |
| 60 | invalid_grant |
these are not the grants you are looking for |
| 61 | invalid_client |
client not found |
| 62 | invalid_request |
client_id was not supplied |
| 63 | invalid_request |
client_secret was not supplied |
| 64 | invalid_client |
Incorrect credentials. Please Retry |
| 65 | invalid_request |
grant_type was not supplied |
| 80 | invalid_request |
invalid channel type |
| 81 | invalid_request |
bad channel handle |
| 83 | invalid_request |
otp not found |
| 84 | invalid_request |
fact verification failed |
| 85 | invalid_request |
otp verification failed |
| 100 | invalid_request |
backend does not know about this username |
| 101 | invalid_request |
code was not supplied |
| 102 | invalid_request |
redirect_uri was not supplied |
| 103 | invalid_request |
code is bad or expired |
| 104 | invalid_grant |
redirect_uri does not match the previous grant |
| 105 | invalid_grant |
this grant was not issued to you! |
| 106 | invalid_request |
refresh_token was not supplied |
| 107 | invalid_request |
refresh disallowed for app |
| 108 | invalid_grant |
bad or expired refresh token |
| 109 | invalid_request |
loginid was not supplied |
| 115 | invalid_request |
unauthenticated client will not be issued token! |
| 117 | invalid_request |
nonce is mandatory for this response_type |
| 118 | invalid_request |
display is invalid |
| 119 | invalid_request |
prompt is invalid |
| 119 | invalid_request |
prompt must be set to consent for offline_access |
Oauth2 Migration Best Practices
Old World Authentication
- The old world authentication is a hybrid oauth2 implementation which has an endpoint that looks like this
/net2/oauth2/ - Client applications are identified by a
ConsumerKeyandSecretpair. Sometimes these are referred to asclient_idandclient_secret. - Access Tokens in the old world have a 12 months expiry period and refresh tokens live forever. This is typically not a good security practice and goes against the Oauth2 standards.
- Tokens that are being used by clients today are issued for WSADMINs, meaning all tokens have administrative access.
New World Authentication
1. Oauth2
- The SAP Concur new Oauth2 implementation follows the established Oauth2 Authorization Framework RFC : https://tools.ietf.org/html/rfc6749
- This new service has an endpoint of
/oauth2/v0/token - Unlike the old world auth, access tokens have a 1 hour expiry and refresh tokens have a 6 months expiry. This is in accordance to the best practice of using short lived tokens.
- This would mean that clients would need to perform token management.
2. Getting Started
- Getting clientID / clientSecret
- Work with the SAP Concur implementation team to obtain a new oauth2
client_idandclient_secretand to define the scope of client's application. - Process will take no longer than 48 hours.
- Implementation Team will respond with new
client_id,client_secret, company'srefreshTokenandexpiry date. - Client stores and configures application with this info.
- Work with the SAP Concur implementation team to obtain a new oauth2
- Client applications should store the following tokens and data in their application.
Refresh Token: This token can change although most of the time this value is the same. Client applications should treat all returned refresh tokens as new values and overwrite the stored values with the new values you get from the response.Refresh Token Expiry: This date should be checked by a daily script and ensure that a refresh_grant is made to keep the refresh token alive indefinitely. If company policy dictates that the token should be allowed to expire, then you can skip this step. Once a refresh token has expired, clients would need to contact SAP Concur's Implementation team to get a new company token.
3. Token Management
Calling APIs with
accessTokens- All APIs within SAP Concur require the calling application present an
accessTokenin the Header using the "Bearer" keyword. - Example:
curl -k -v -H "Accept: application/json" \ -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IjE0NTU2MTQzNDYifQ.eyJhdWQiOiIqIiwic3ViIjoiaHR0cDovL21zcGNzcHJzcnFhLmNvbmN1ci5jb25jdXJ0ZWNoLm9yZzozMDAzL3Byb2ZpbGUtc2VydmljZS92MS91c2Vycy83NjAwOUFEMy1GNzdCLTREOTgtQTIxQS01NTNDOUM5MTc5RjAiLCJpc3MiOiJodHRwczovL2NvbmN1ci5jb20iLCJleHAiOjE0NzM4OTUxMjksImxlZ2FjeV9hcHBsaWNhdGlvbl9pZCI6MTUwMDA2MzY1OSwidXNlclVSSSI6Imh0dHA6Ly9tc3Bjc3Byc3JxYS5jb25jdXIuY29uY3VydGVjaC5vcmc6MzAwMy9wcm9maWxlLXNlcnZpY2UvdjEvdXNlcnMvNzYwMDlBRDMtRjc3Qi00RDk4LUEyMUEtNTUzQzlDOTE3OUYwIiwidXNlcnV1aWQiOiI3NjAwOUFEMy1GNzdCLTREOTgtQTIxQS01NTNDOUM5MTc5RjAiLCJuYmYiOjE0NzM4OTE1MjksImh0dHBzOi8vYXBpLmNvbmN1cnNvbHV0aW9ucy5jb20vYXBwIjoiaHR0cHM6Ly9hcGkuY29uY3Vyc29sdXRpb25zLmNvbS9hcHAtbWdtdC92MC9hcHBzL2UwMTBlMjVkLWI0Y2UtNGNlMy1hN2U0LWI2NzBjYjFhZGNiMCIsImh0dHBzOi8vYXBpLmNvbmN1cnNvbHV0aW9ucy5jb20vc2NvcGVzIjpbIkNDQVJEIiwiQ09NUEQiLCJVU0VSIiwidXNlcl9yZWFkIiwiRU1FUkciLCJKT0JMT0ciLCJFUkVDUFQiLCJJVElORVIiLCJGSVNWQyIsIkxJU1QiLCJQQVNTViIsIkNPTkZJRyIsIkZPUCIsIkdIT1NUIiwiQ09OUkVRIiwiVFJJUElUIiwiQ09NUEFOWSIsInByb2ZpbGUiLCJFVlMiLCJlbWFpbCIsIlRSVlBUUyIsIkFUVEVORCIsIklOVlBPIiwiTk9USUYiLCJUUlZSRVEiLCJTVVBTVkMiLCJFWFBSUFQiLCJhZGRyZXNzIiwiRVhUUkNUIiwiUEFZQkFUIiwid3Jvbmdfc2NvcGUiLCJJTlZQTVQiLCJJTUFHRSIsIlRBWElOViIsIlJDVElNRyIsIlVOVVRYIiwiVFdTIiwiVE1DU1AiLCJCQU5LIiwiSU5WVkVOIiwib3BlbmlkIiwiTVRORyIsIklOU0dIVCIsIlRSVlBSRiIsIklOVlRWIiwiTUVESUMiLCJUU0FJIl0sImlhdCI6MTQ3Mzg5MTUyOX0.QHY4Mc5A3J981-HDv7KUdgS4tUI-qnmQAxwe9J6DHxuMmYSoGEYZ0dsnLnqc2lO2iVJK6Pg3EBZTArq8_vzV2FK7tA4-IT1eCEHo1e-RWZyWLnR7P56SvZozXpY73daovSH7572HrUm21FXcyLmdaLZyo2LfFcChaghbSCjm1Jg1duH-pLPUW4d89-_pdakmyxfV3GCm2N_XQXoRhNYAAiZcG8UfxEn3TpMHJ96F2n6keJanT_Sn2Sek_sH2EmeeCpg5-jDe0fvLvr1-gY5t0ifq8QBKWHSUUIrGbQvseD6CGzfyiFUqVypN2lukfWACR-26otN50c0OzY6kgY06RA" \ https://us.api.concursolutions.com/profile/v1/me - More documentation here: https://developer.concur.com/api-reference/authentication/getting-started.html
- All APIs within SAP Concur require the calling application present an
Refreshing expired
accessTokens- Since
accessTokenshave a one hour expiry, clients would need to get a newaccessTokenbefore any API call is made. - In order to obtain a new
accessToken, clients should call Oauth2 using therefresh_grantand providing the oldrefreshTokenand other additional fields. In the error handling code, clients need to handle
accessTokenexpiry errors. If theaccessTokenis expired in the middle of processing, the following should happen:- Code should call Oauth2's
refresh_grantto get a newaccessToken - Overwrite the existing
refreshTokenwith the new one. - Update
expiry dateforrefreshToken - Retry the API call.
- Code should call Oauth2's
More details about refreshing tokens here: https://developer.concur.com/api-reference/authentication/apidoc.html#refresh_token
- Since
Handling errors
- There are a few error codes that client applications should be aware of.
403 Forbidden: Requesting for tokens for users who cannot be requested for. Usually for companies that are not authorized by their administrators.- The bulk of errors will be returned as 400 errors and the response contains a
codeanddescription. Client applications should look for these values to determine what to do next.
Code Desc Comment 05 Incorrect credentials. clientID / secret not correct, or authtoken/password not correct 10 Account is disabled 14 Account is locked 16 User lives elsewhere There will be a geolocation field in the response to this error message. Use this as the base URL and retry the call. 54 Invalid Scope requested scope exceeds what is permitted. - for a full list, review this doc: https://developer.concur.com/api-reference/authentication/apidoc.html#response_codes
4. Old auth v.s. new auth diagram

List of Scopes for all SAP Concur APIs
Scope is a parameter as defined in the OAuth 2.0 standards (RFC6749) to enable a client to specify the scope of the access request. The value of the scope parameter is expressed as a list of space-delimited, case-sensitive strings although some implementations of scope uses a comma-delimited format. Scopes limit access for OAuth2 tokens and do not grant any additional permission beyond that which the client already has.
Scopes apply to applications only. Scopes play a crucial part in defining the ultimate access to a resource by a User.
User’s Roles / Permissions + Claims + Application Scopes
Naming Conventions
Concur services follow these standard naming conventions for scopes.
Template: {resource}.{optional subresource}.{action}
Examples: mileage.rate.read
receipts.read
List of v4 Actions
{actions} are common authorizations across resources.
| Action | Description | Examples |
|---|---|---|
read |
Read only access (GET) | receipts.read, budgetitem.read |
write |
Read AND Write access (GET, POST, UPDATE etc) | company.write, travel.receipts.write |
writeonly |
Write only access | mileage.journey.writeonly, receipts.writeonly |
delete |
Delete access | N/A |
List of v4 API Scopes
These are the list of scopes for the v4+ APIs.
| Scope | Description |
|---|---|
| budgetitem.read | Read access to budget data including fiscal calendar |
| budgetitem.write | Read and write access to budget data including fiscal calendar |
| company.read | Read company profile |
| company.write | Read and Write company profile |
| creditcardaccount.read | Read credit card account data |
| expense.report.read | Read only access to expense reports, expenses and allocations |
| expense.report.readwrite | Read and write access from/to expense reports, expenses and allocations |
| expense.report.workflowstatus.write | Access to approve/reject an expense report |
| fiscalcalendar.read | Access to fiscal calendar |
| fiscalcalendar.write | Read and write access to fiscal calendar |
| invoice.providerpayment.write | Read access to pending payments, and write access to payment status |
| mileage.journey.read | Read-only access to mileage journey resources |
| mileage.journey.writeonly | Write-only access to mileage journey resources |
| mileage.rate.read | Read-only access to rate configuration resources |
| mileage.rate.writeonly | Write-only access to rate configuration resources |
| mileage.vehicle.read | Read-only access to vehicle resources |
| mileage.vehicle.writeonly | Write-only access to vehicle resources |
| openid | Return OPENID token |
| purchaserequest.write | Write only access to purchase requests |
| purchaserequest.read | Read only access purchase requests |
| quickexpense.writeonly | Write quick expense |
| realtimeingest.location.writeonly | Post user location object upon trip completion |
| receipts.read | Read receipts and invoices |
| receipts.write | Read and Write receipts and invoices |
| receipts.writeonly | Write only access for receipts and invoices |
| travelallowance.itinerary.read | Read only access to itinerary data |
| travelallowance.itinerary.writeonly | Write only access to itinerary data |
| travelallowance.configuration.read | Read only access to itinerary configuration data |
| travelallowance.configuration.writeonly | Write only access to itinerary configuration data |
| travelallowance.itineraryresult.read | Read only access to itinerary result data |
| travel.receipts.read | Read requests for travel receipts |
| travel.receipts.write | Read and write travel receipts |
| travelrequest.write | Read and write travel requests |
| user.read | Read user profile |
| user.write | Read and write user profile |
List of Connect API scopes
These are the list of scopes for the existing CONNECT APIs (v1.0 - v3.1)
| Scope | Description |
|---|---|
| user_read | Read user profile for old USER APIs |
| ATTEND | Attendee List - Add, Update, or Inactivate Attendees |
| CONFIG | Expense Configuration - Update Expense Feature Configuration |
| CONREQ | Connection Request - Get or update connection requests to travel reward programs |
| ERECPT | E-Receipts Provider - Post receipts and invoices, get matching facts |
| EVS | External Validation - Validate Fields Using External Systems |
| EXPRPT | Expense Report - Add, Approve, or Update Expense Reports |
| CCARD | Expense Report - Add, Approve, or Update Expense Reports |
| BANK | Expense Report - Add, Approve, or Update Expense Reports |
| EXTRCT | Extract - Request Extract of Available Data |
| FISVC | Financial Integration - Migrate transactions from Concur to external systems |
| FOP | Form of Payment - Access and update user form of payment information |
| GHOST | Form of Payment - Access and update user form of payment information |
| IMAGE | Imaging - Add or Retrieve Report and Line Item Images |
| INSGHT | Insights - Additional services marketable to users |
| INVPMT | Payment Request - Create ,Retrieve and Update for Payment Request |
| INVPO | Purchase Orders - Add or Update Purchase Orders |
| INVTV | Invoice - Tax Validation |
| INVVEN | Search, Add, Update or Delete Vendors |
| ITINER | Itinerary - Add or Update Itineraries or Bookings |
| JOBLOG | Job Log - Log Start, Detail, End and Ping |
| LIST | List Items - Add, Update, or Delete List Items |
| MTNG | Meeting - Attendee Travel Booking |
| NOTIF | Notifications - View and manage notifications |
| PAYBAT | Payment Batch - Close Batches and Request Batch Export Files |
| RCTIMG | Receipts - Add or Update Receipt and OCR Images |
| SUPSVC | Supplier Service - Get Supplier Data |
| TAXINV | Digital Tax Invoice - Get or Validate Digital Tax Invoices |
| TRVPRF | Travel Profile - Access and update user travel profile information |
| PASSV | Travel Profile - Access and update user travel profile information |
| COMPD | Travel Profile - Access and update user travel profile information |
| EMERG | Travel Profile - Access and update user travel profile information |
| TSAI | Travel Profile - Access and update user travel profile information |
| TMCSP | Travel Profile - Access and update user travel profile information |
| MEDIC | Travel Profile - Access and update user travel profile information |
| UNUTX | Travel Profile - Access and update user travel profile information |
| TRVPTS | Travel Points - Access User Balances and Post Travel Points Transactions |
| TRVREQ | Travel Request - Add, Update or Delete Travel Requests |
| TWS | Travel Approval - Approve or Reject Travel Itineraries |
| USER | Users- Add or Update User Accounts |
| COMPANY | Companies - Add or Update Company profile |
Sign in with Concur
Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.
Introduction
Streamline user onboarding with Sign in with Concur – a new feature that allows new users to log on to a partner application using their Concur credentials. Similar to the single sign-on feature provided by Facebook and other social applications, Sign in with Concur reduces the time and effort involved in setting up an account with our partner apps.
Benefits
For partners
- Streamlines account set-up: User's profile is pre-validated, including basic PII information plus travel preferences
- Simplifies development and integration: Quickly obtain authentication tokens for the user and call SAP Concur APIs
For users
- Quick and hassle-free way to sign up for a new app
- Secure: User's Concur credentials are never shared with partners
Use Cases
Sign in with Concur solves access and support issues for all of our various types of partner integrations:
Consumer applications
Business travelers use in-policy providers but may not have an existing loyalty account. Gain access to the network of business travelers and expense users of Concur by simplifying their first purchase.
Front office applications
Travel and Expense Policy administrators reduce the company's cost via volume purchasing through your application or service; reduce your integration and support overhead as well by removing the need to manage individual user accounts associate with those customers.
Back office applications
Automate the process of provisioning users for your application using data from Concur.
Simplify log in and support for users that log in infrequently by leveraging the SAP Concur authentication.
How it Works
Select Sign in with Concur from the site login menu

Pick Authentication Option
Single-sign on users can utilize the "Send a link to my email" option.

If the user selects "One-time Link":
Enter Email address

Confirmation page

Email example

If the user selects "Enter Concur Credentials":

Complete!
For both authentication flows, once authorized, the account is provisioned and user is logged in

Getting Started
1. Obtain your Application clientID and clientSecret
Before you can integrate Sign in with Concur into your application, you need to register your application with Concur. You can do this by contacting your Partner Enablement Manager or Partner Account Manager. Once you have registered an application, you will receive a clientId and clientSecret. The clientId is a unique UUID4 identifier for your application, and the clientSecret is your application password. You will be using this credential to obtain tokens either for the application itself, or on behalf of a user.
2. Add the button to your application
The first script adds the Concur style library to your page and the second applies the style to your button.
<script
data-client-id=[yourClientID]
data-redirect-uri=[yourRedirectURI]
data-oauth-uri="https://www-us.api.concursolutions.com"
src="https://static.concursolutions.com/nui/oauth/0.0.1/concur-signin.js">
</script>
<div style="float:right">
<div id="concur-signin"></div>
</div>
Clicking this button renders the Sign in with Concur screen which presents two options to the user for signing in: 1) using Concur credentials OR 2) using a link sent via email.
Option 2 is designed for users who do not want to use passwords or those that do not have passwords such as Single Sign On (SSO) users.

3. Handle Authorization Completion
When users choose the email option, an email will be sent to the user that contains the redirect_uri chosen by the partner in Step 1. If the user selects the username and password option, after accepting the scopes, the user is also sent to the redirect_uri provided.
There will also be a temporary one-time use code which is appended to this redirect_uri. For example, if our redirect URI is https://www.hipmunk.com/auth/concur/callback, the code will be returned as:
https://www.hipmunk.com/auth/concur/callback?cc=<token>
The call to this redirect_uri will contain a temporary code cc which should be used to obtain an official oauth2 accesstoken and refreshtoken.
The response for a successful call will look like this:
**HTTP/** 1.1200 **OK**
;Content-Type: application/json
Date: date-requested
Content-Length: 3397
Connection: Close
{
"expires_in":"3600",
"scope":"app-scope",
"token_type":"Bearer",
"access_token":"new-access_token",
"refresh_token":"new-refresh_token",
"refresh_expiry":"refresh_token_expiry",
"geolocation":"https://us.api.concursolutions.com"
}
4. Retrieve User Profile information
Once the partner completes the oauth2 flow, they receive an access_token and refresh_token. Using the access_token and within the hour lifetime of the token, the partner has the ability to call SAP Concur APIs. Your application may call the Profile API to obtain user information in order to provision an account in the partner's application.
TripLink Suppliers see the appendix for more details.
Here's an example to retrieve profile information for a User in the Production environment using cURL ( Base URIs for other Environments):
curl -k -v -H "Accept: application/json"\
-H "Authorization: Bearer …ypN2lukfWACR-26otN50c0OzY6kgY06RA"\
https://us.api.concursolutions.com/profile/v1/me
The response from the Profile service will be a compact version of the User profile. The schema can be found here.
5. Create user's account and log user into partner application immediately for a seamless user experience.
Once the user is logged in, your application must determine whether an existing account exists. Your application can do so by pulling user information from the application and SAP Concur profile.
Existing Accounts
For users connected to SAP Concur through the Concur App Center or otherwise, your application can match the SAP Concur unique user ID.
New SAP Concur Accounts
For users with existing, non-SAP Concur accounts , the unique user information in your application can be matched with information in SAP Concur (e.g. email address).
If the user does not have an existing account , your application must provision a user account. In this case, the partner maintains the user's profile over time. This is beneficial as it allows the app to post data for the user following the initial session. For example, it allows users make changes to a reservation and receive updates within SAP Concur and/or receive receipts for services charged after delivery such as hotel stays.
In all cases, the user's token, geolocation and user UUID should be stored. As applications vary in the information required to create a new user record and utilize the service, your application should leverage data from the user profile endpoint where possible.
Account Maintenance
Once the account is provisioned or matched, the application must:
- Provide the option to disconnect
- Maintain the user's session. Once the session is established, your application's typical session maintenance should be observed. This includes idle timeout and session refresh, where applicable. The issued token will have a predetermined expiration. To maintain the connection, please see the token refresh documentation.
Error Handling
In all cases, the error description provided by Concur should be displayed to the user.
The following covers special cases that require additional handling.
Authorization Declined
In the case the user leaves the sign in process or sign in is unsuccessful, the user will be redirected to the following:
Your_Redirect_Uri?
error_code=user_denied
&error_description=The+user+denied+your+request.
Apps should then provide the user with alternative connection methods:
- Log in by creating an account
- Attempt Sign in with Concur with an alternate credential
Application is disabled
Customers have the option to disable applications for their users. In these cases, the user will be redirected to the following:
Your_Redirect_Uri?
error_code=
&error_description=
In this case, the user will not be able to access your application using Sign in with Concur. The error description should be displayed to the user and the user given alternate sign in methods (e.g. create an account).
Advanced
This section covers guidelines for specific Sign in with Concur implementations.
Enterprise Applications
Company-wide integrations are unique in that your application will interact with SAP Concur both on a batch level (for example, GET or POST for multiple employees) but also allow individuals to sign in to the service without creating a new account.
When an application supports enterprise integrations, the user's account should be associated with the company's information (company UUID) so that the company token can be used to process batch transactions.
In addition, the administrator will need to identify the users which should have access to your application. Given that, the administrator must first add users to your service. An example of the set up and sign in process are documented below.
Sign in with Concur Set Up
The below diagram illustrates the initial set up process. To set up the connection, the administrator must identify the users of your service.
Note that, in addition to identifying users of the service, your application may also require that roles/permissions be assigned to individual users to determine access to various features and functionality of your service. Role and permissions assignment are not depicted in the diagram below as the requirements may differ for each client application.
Once added to the service, users must then verify their identity before first sign in. This process uses the One-Time Password Grant to first validate the user is the owner of the email address used to uniquely identify that individual. Once validated, the user may sign in with username and password going forward.

Signing in to the Client Application
When a user first navigates to your application, you may offer multiple sign in options, including Sign in with Concur. Once signed in, your application must validate that users have completed the one-time verification.
If the user has not completed the one-time verification when visiting your site, the One-Time Password Grant should be initiated on the user's behalf.
The below illustrates the process for users signing in to your service.

TripLink Configurations
Depending on the products the customer has enabled, integrations and features available with Sign in with Concur vary. The following defines the scopes that are applicable product combinations. Your application must support each of the below potential scope configurations:
- Travel Users
- TripLink Access:
- Travel Profile
- Client Discount Code
- User form of Payment
- Ghost Card
- Itinerary
- E-Receipt
- Non-Triplink Access:
- Travel Profile
- E-receipt
- Expense Only Access:*
- E-receipt
* Special Note: For TripLink Suppliers that support the Travel Receipts API, this API does not support Expense only users. It is recommended that e-receipts be posted for these or all users via the Receipts API.
To determine which permissions the user has access to, each time a user signs in *, your application should:
- Call the User Profile API to get the user's permissions.
A user can have one or more permissions that will dictate the scopes applicable to that user.
curl -k -v -H "Accept: application/json"\
-H "Authorization: Bearer …ypN2lukfWACR-26otN50c0OzY6kgY06RA"\
https://us.api.concursolutions.com/api/user/v1.0/user
The detailed response can be found here: /api-reference/user/ (snippet below).
| Name | Type | Format | Description | | --- | --- | --- | --- | | ExpenseUser | string | | Whether the user has access to Expense. Format: Y/N. | | TripUser | string | | Whether the user has access to Travel. Format: Y/N. |
The response will indicate whether the is an Expense or Travel user.
If an expense user only , only the e-receipts scope is applicable and the user will not be eligible for other travel discounts or automated itinerary creation in Concur.
If a travel user, use the token to call the Travel Profile API .
Within this response, is the "HasOpenBooking" parameter; if "true" the user is eligible for TripLink.
If the user has travel only, they will not receive e-receipts.
- Store the user permissions information. (optional)
The user's permissions can then be used to determine which scopes and APIs are applicable for updates to an existing booking and/or e-receipts.
- The user's permissions can change at any time. It is recommended that the permissions be checked each time the user logs in to determine whether new functionality is available to the user. *
Supported Languages
The following language codes are supported in by Sign in with Concur.
| Code | Name |
|---|---|
| en | English (US) |
BUDGET
Budget v4 - Getting Started
Overview
The Budget service exposes budget and fiscal year data. Partners and clients may use the service endpoints to read and alter fiscal year, budget, budget adjustment, and budget matching configuration. Summary and detailed balance amounts are also available to read, but may not be altered via the API.
The sequence to configure budgets is to first setup the fiscal year and then the budget categories (if applicable) before creating budget items. Budget items may use budget tracking fields as filters. The budget tracking field can only be configured in the application UI. Also budget owner, approver, and budget viewer permissions have to be assigned to users prior to configuring budgets.
Process Flow

Products and Editions
- Concur Request Professional Edition
- Concur Request Standard Edition
- Concur Expense Professional Edition
- Concur Expense Standard Edition
- Concur Invoice Professional Edition
- Concur Invoice Standard Edition
Scope Usage
This API requires one or more of the following scopes:
| Name | Description | Endpoint |
|---|---|---|
budgetitem.read |
Grants read access to the budget resources. | GET Budget Category, GET Budget Item, GET Budget Tracking Fields, GET Fiscal Year, GET Valid Expense Types |
budgetitem.write |
Grants read and write access to the budget resources. | GET Budget Category, GET Budget Item, GET Budget Tracking Fields, GET Fiscal Year, GET Valid Expense Types, POST Budget Adjustment, POST Budget Category, POST Budget Item, POST Fiscal Year, DELETE Budget Category, DELETE Budget Item, DELETE Fiscal Year |
fiscalcalendar.read |
Grants read access to the fiscal calendar. | GET All Fiscal Years, GET a Fiscal Year |
fiscalcalendar.write |
Grants read and write access to the fiscal calendar. | GET All Fiscal Years, GET a Fiscal Year, POST a Fiscal Year, DELETE a Fiscal Year |
Dependencies
SAP Concur clients must purchase Budget in order to use this API.
Access Token Usage
This API supports both company level and user level access tokens. The user needs to have the Budget Administrator role in order to access the API.
Budget v4 - Budget Adjustments
This resource is used to add budget adjustments. Each budget item detail may have one or more budget adjustments and adjustments can be made to manually add or subtract the budget, spent or pending balances.
Create a Budget Adjustment
Create one or more budget adjustments.
- If the rolling adjustment feature is used, all adjustments for a given month, adjustment type, amount type, budget, and description will be combined into one adjustment. See Parameters below.
- The combination of budget item name, fiscal year name, fiscal period name, and owner email determine which budget the adjustment affects. See Schema below
- The amount type determines how the adjustment affects the budget. The budget amount adjustment reduces or increases the top-line budget amount while spent and pending amounts affect the budget balances.
- Adjustments may not be deleted or updated via the API.
Scopes
budgetitem.write - Refer to Scope Usage for full details.
Request
URI
Template
POST /budget/v4/adjustments
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
useMonthlyRollingUpdate |
boolean |
query |
Required If true, all adjustments for a given month, adjustment type, amount type & description will be rolled up to one adjustment. This is useful for an automated process that makes daily or weekly updates and doesn't want to clutter end-user dashboards. |
Headers
Payload
Response
Status Codes
- 200 OK Successful call, response is in body.
- 400 Bad Request The request was determined to be invalid by the server. Possibly a validation failed on the data that was sent in the payload. The response will have a list of validation errors in the body. See below for an example 400 response.
- 403 Forbidden The user does not have the necessary permissions to perform the request.
- 404 Not Found The resource could not be found or does not exist.
- 500 Internal Server Error Error message in response body.
- 504 Gateway Timeout Error message in response body.
Headers
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7231 Allow
- RFC 7234 Cache-Control
- RFC 7230 Content-Length
- RFC 7231 Content-Type
- RFC 7231 Date
- RFC 7234 Expires
- RFC 7232 ETag
- RFC 7234 Pragma
- RFC 7231 Server
- RFC 7231 Vary
Payload
Either "Success" or an Error Response
Example
Request
POST https://us.api.concursolutions.com/budget/v4/adjustments?useMonthlyRollingUpdate=false
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json
[
{
"budgetItemName":"API Budget-Oregon",
"fiscalYearName": "2018",
"budgetOwnerEmail": "m.jones@example.com",
"fiscalPeriodName": "2018 - Q3",
"amount": 100,
"adjustmentType": "FUND_TRANSFER",
"amountType": "BUDGET_AMOUNT",
"description": "Initial July Adjustment",
"transactionDate": "2018-07-11"
},
{
"budgetItemName":"API Budget-Travel",
"fiscalYearName": "2018",
"budgetOwnerEmail": "m.jones@example.com",
"fiscalPeriodName": "2018 - Q3",
"amount": 100,
"adjustmentType": "EXPENSE",
"amountType": "SPENT_AMOUNT",
"transactionDate": "2018-07-10"
}
]
Response
Success Response
HTTP/1.1 200 OK
Cache-Control: no-store
Connection: keep-alive
Content-Length: 9
Content-Type: application/json;charset=utf-8
Date: Fri, 21 Sep 2018 15:24:27 GMT
Expires: Thu, 20 Sep 2018 15:24:27 GMT
Pragma: no-cache
Vary: Origin
concur-correlationid: 86a0d9fe-9e98-43c3-89d8-a2917dd844cb
"Success"
Failure Response
HTTP/1.1 400 Bad Request
Cache-Control: no-store
Connection: close
Content-Length: 242
Content-Type: application/json;charset=utf-8
Date: Fri, 21 Sep 2018 15:29:05 GMT
Expires: Thu, 20 Sep 2018 15:29:05 GMT
Pragma: no-cache
concur-correlationid: 561ce34c-6542-4bae-82a2-aa6ccd8c6b22
{
"message": {
"status" : false,
"errorMessageList" : [
{
"errorType" : "ERROR",
"errorCode" : "BUDGET.BUDGET_PERIOD_REQUIRED",
"errorMessage" : "Record 1) Record 1) Budget period is missing"
}
]
}
}
Schema
Budget Adjustment
| Name | Type | Format | Description |
|---|---|---|---|
budgetItemName |
string |
- | Required The name of the budget of the adjustment. |
fiscalYearName |
string |
- | Required The name of the budget’s fiscal year. The default name for a fiscal year is the numeric, four-digit year. Example: 2019 |
fiscalPeriodName |
string |
- | Required The specific fiscal period when this budget amount will be used. The default name for a fiscal period is: Monthly: <fiscal year name> - <three-letter month abbreviation> (Example: 2019 - Jun). Quarterly: <fiscal year name> - Q<number of quarter> (Example: 2019 - Q2). Yearly: <fiscal year name> (Example: 2019). |
budgetOwnerEmail |
string |
- | Required The user who is responsible for the budget, as configured. |
amount |
decimal |
- | Required The budget currency amount to be adjusted. The amount may be a positive or negative value but it cannot be zero. |
adjustmentType |
string |
- | Required The type of adjustment being made. Only a user reference field. Supported values: BUDGET_BALANCE, FUND_TRANSFER, EXPENSE, PAYMENT_REQUEST, PURCHASE_REQUEST, REQUEST |
amountType |
string |
- | Required The type of the budget’s balance to adjust. Affects which values in the budget are updated. Supported values: BUDGET_AMOUNT, SPENT_AMOUNT, PENDING_AMOUNT |
description |
string |
- | A user-friendly description of the adjustment. |
transactionDate |
date |
YYYY-MM-DD |
Required if amount type is either SPENT_AMOUNT or PENDING_AMOUNT The transaction date of adjusted spend. Must be within the fiscal period. |
Error Response
| Name | Type | Format | Description |
|---|---|---|---|
status |
boolean |
- | False if there was an error. |
errorMessageList |
array |
errorMessage |
List of all errors detected. |
Error Message
| Name | Type | Format | Description |
|---|---|---|---|
errorType |
string |
- | WARNING or ERROR. |
errorCode |
string |
- | Text code for this error. |
errorMessage |
string |
- | Plain language error message. |
Budget v4 - Budget Category
This resource is used to retrieve and update budget categories which are collections of expense types used for budget matching. Each budget item header may have one Budget Category. If it does, only line items with expense types contained in that Budget Category will be accumulated to the budget.
- GET All Budget Categories
- GET a Budget Category
- POST a Budget Category
- DELETE a Budget Category
- GET All Valid Expense Types
- Schema
- Response Headers
GET All Budget Categories
Retrieve a list of all budget categories.
Scopes
This API call requires one of the following scopes:
budgetitem.read- Refer to Scope Usage for full details.budgetitem.write- Refer to Scope Usage for full details.
Request
URI
Template
GET /budget/v4/budgetCategory
Parameters
N/A
Headers
Response
Status Codes
- 200 OK Successful call, response is in body.
- 400 Bad Request The request was determined to be invalid by the server.
- 403 Forbidden The user does not have the necessary permissions to perform the request.
- 500 Internal Server Error Error message in response body.
- 504 Gateway Timeout Error message in response body.
Headers
Payload
Example
Request
GET https://us.api.concursolutions.com/budget/v4/budgetCategory
Authorization: Bearer {token}
Content-Type: application/json
Response
HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 1292
concur-correlationid: 9d59b6f0-e5bd-47bf-bcad-4c3de9f5c45c
[
{
"name":"Marketing and Outreach",
"description":null,
"statusType":"OPEN",
"id":"36047f6c-6cf6-443d-a952-39efb012acdb",
"expenseTypes":[
{
"featureTypeCode":"PURCHASE_REQUEST",
"expenseTypeCode":"MKTG",
"id":"f35827a8-7981-4a5b-bfc3-da7ebb4665ff",
"name":null
},
{
"featureTypeCode":"EXPENSE",
"expenseTypeCode":"SEMNR",
"id":"30f16783-e50e-4ab4-b6fb-f66cc75956f2",
"name":null
},
{
"featureTypeCode":"PURCHASE_REQUEST",
"expenseTypeCode":"ADVT",
"id":"64a04928-37b0-49c8-99e8-c346e6d47825",
"name":null
}
]
},
{
"name":"Airfare",
"description":null,
"statusType":"OPEN",
"id":"459fe79a-9b1e-4ea0-8416-19de0ff14eef",
"expenseTypes":[
{
"featureTypeCode":"EXPENSE",
"expenseTypeCode":"AIRFR",
"id":"53300041-3fb9-4a93-8cdf-327fcbe74a0c",
"name":null
},
{
"featureTypeCode":"REQUEST",
"expenseTypeCode":"AIRFR",
"id":"29278c5a-624a-4dd6-a2c1-02dd233d3fbf",
"name":null
}
]
}
]
GET a Budget Category
Retreive the details of a single budget category.
Scopes
This API call requires one of the following scopes:
budgetitem.read- Refer to Scope Usage for full details.budgetitem.write- Refer to Scope Usage for full details.
Request
URI
Template
GET /budget/v4/budgetCategory/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
| id | string |
uuid |
The budget category's key field. |
Headers
Response
Status Codes
- 200 OK Successful call, response is in body.
- 400 Bad Request The request was determined to be invalid by the server.
- 403 Forbidden The user does not have the necessary permissions to perform the request.
- 404 Not Found The resource could not be found or does not exist.
- 500 Internal Server Error Error message in response body.
- 504 Gateway Timeout Error message in response body.
Headers
Payload
Example
Request
GET https://us.api.concursolutions.com/budget/v4/budgetCategory/36047f6c-6cf6-443d-a952-39efb012acdb
Authorization: Bearer {token}
Content-Type: application/json
Response
HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 642
concur-correlationid: f7b1a193-46cc-4784-9c6f-d8e1e47ecaa1
{
"name":"Marketing and Outreach",
"description":null,
"statusType":"OPEN",
"id":"36047f6c-6cf6-443d-a952-39efb012acdb",
"expenseTypes":[
{
"featureTypeCode":"PURCHASE_REQUEST",
"expenseTypeCode":"MKTG",
"id":"f35827a8-7981-4a5b-bfc3-da7ebb4665ff",
"name":null
},
{
"featureTypeCode":"EXPENSE",
"expenseTypeCode":"SEMNR",
"id":"30f16783-e50e-4ab4-b6fb-f66cc75956f2",
"name":null
},
{
"featureTypeCode":"PURCHASE_REQUEST",
"expenseTypeCode":"ADVT",
"id":"64a04928-37b0-49c8-99e8-c346e6d47825",
"name":null
}
]
}
POST a Budget Category
Save a new budget category or update an existing budget category.
- When adding expense types to a budget category, only the feature type code and expense type code are needed.
- Since Expense Report expense types are shared with Request and Payment Request (Invoice) expense types are shared with Purchase Request, only EXPENSE and PAYMENT_REQUEST expense types must be supplied. The types will be copied to REQUEST and PURCHASE REQUEST automatically.
- If an expense type is supplied but the feature is not enabled, it will have no effect. For example, an Invoice-Maintenance expense type can be added to a Budget Category if Invoice is not enabled for Budget--it will not change how spending is assigned to budgets.
Scopes
budgetitem.write - Refer to Scope Usage for full details.
Request
URI
Template
POST /budget/v4/budgetCategory
Parameters
N/A
Headers
Payload
Response
Status Codes
- 200 OK Successful call, response is in body.
- 400 Bad Request The request was determined to be invalid by the server. Possibly a validation failed on the data that was sent in the payload. The response will have a list of validation errors in the body. See below for an example 400 response.
- 403 Forbidden The user does not have the necessary permissions to perform the request.
- 404 Not Found The resource could not be found or does not exist.
- 500 Internal Server Error Error message in response body.
- 504 Gateway Timeout Error message in response body.
Headers
Payload
Budget Category or Error Response
Example
Request
POST https://us.api.concursolutions.com/budget/v4/budgetCategory
Authorization: Bearer {token}
Content-Type: application/json
{
"name": "Advertising Category",
"description": "Advertising",
"expenseTypes": [
{
"featureTypeCode": "EXPENSE",
"expenseTypeCode": "ADVT"
},
{
"featureTypeCode": "PAYMENT_REQUEST",
"expenseTypeCode": "ADVT"
}
],
"statusType": "OPEN"
}
Response
Success Response
HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 1270
concur-correlationid: 5c00e59f-d00c-4019-8d3d-47130d8e37b4
{
"name": "Advertising Category",
"description": "Advertising",
"id": "d9fd5191-7016-4f50-a6c8-4770bddc01d8",
"statusType": "OPEN",
"expenseTypes": [
{
"id": "e1dd44da-25b4-4180-8d89-00f3a8d8cf4e",
"featureTypeCode": "EXPENSE",
"expenseTypeCode": "ADVT",
"name": null
},
{
"id": "67253ac1-77e0-4d61-a478-0d194611b320",
"featureTypeCode": "PAYMENT_REQUEST",
"expenseTypeCode": "ADVT",
"name": null
}
]
}
Failure Response
HTTP/1.1 400 Bad Request
Cache-Control: no-store
Connection: close
Content-Length: 338
Content-Type: application/json;charset=utf-8
Date: Fri, 21 Sep 2018 15:27:05 GMT
Expires: Thu, 20 Sep 2018 15:27:05 GMT
Pragma: no-cache
concur-correlationid: 44adb686-a624-4ee5-b618-e4ea31a95bec
{
"status" : false,
"errorMessageList" : [
{
"errorType" : "ERROR",
"errorCode" : "BUDGET.BUDGET_CATEGORY_NAME_REQUIRED",
"errorMessage" : "Budget category name is required"
},
{
"errorType" : "ERROR",
"errorCode" : "BUDGET.BUDGET_CATEGORY_NAME_UNIQUE_ERROR",
"errorMessage" : "Budget category must have a unique name"
}
]
}
DELETE a Budget Category
Delete a budget category. Budget categories that are in use by budget items may not be deleted.
Scopes
budgetitem.write - Refer to Scope Usage for full details.
Request
URI
Template
DELETE /budget/v4/budgetCategory/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
| id | string |
uuid |
The budget category's key field. |
Headers
Response
Status Codes
- 200 OK Successful call, response is in body.
- 400 Bad Request The request was determined to be invalid by the server.
- 403 Forbidden The user does not have the necessary permissions to perform the request.
- 404 Not Found The resource could not be found or does not exist.
- 500 Internal Server Error Error message in response body.
- 504 Gateway Timeout Error message in response body.
Headers
Example
Request
DELETE https://us.api.concursolutions.com/budget/v4/budgetCategory/a5e00b3f-b941-4522-8b0e-07412fb2cc7c
Authorization: Bearer {token}
Content-Type: application/json
Response
HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 0
concur-correlationid: 39216840-2808-4c49-8874-e9862d96fdb6
GET All Valid Expense Types
Retrieve a list of all possible expense types that may be used in a budget category.
- The list for REQUEST expense types is identical to the list for EXPENSE expense types and similarly PURCHASE_REQUEST is identical to PAYMENT_REQUEST. Due to response size and performance concerns, only EXPENSE and PAYMENT_REQUEST are returned and the caller should assume that identical expense types exist for REQUEST and PURCHASE_REQUEST.
Scopes
This API call requires one of the following scopes:
budgetitem.read- Refer to Scope Usage for full details.budgetitem.write- Refer to Scope Usage for full details.
Request
URI
Template
GET /budget/v4/budgetCategory/expenseTypes
Parameters
N/A
Headers
Response
Status Codes
- 200 OK Successful call, response is in body.
- 400 Bad Request The request was determined to be invalid by the server.
- 403 Forbidden The user does not have the necessary permissions to perform the request.
- 500 Internal Server Error Error message in response body.
- 504 Gateway Timeout Error message in response body.
Headers
Payload
Example
Request
GET https://us.api.concursolutions.com/budget/v4/budgetCategory/expenseTypes
Authorization: Bearer {token}
Accept: application/json
Response
HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 367
concur-correlationid: 7afa7091-bc4e-4408-8248-a67f9e24a023
[
{
"featureTypeCode":"EXPENSE",
"expenseTypeCode":"AIRFR",
"id":null,
"name":"Airfare"
},
{
"featureTypeCode":"EXPENSE",
"expenseTypeCode":"AIRTX",
"id":null,
"name":"Airfare Ticket Tax"
},
{
"featureTypeCode":"PAYMENT_REQUEST",
"expenseTypeCode":"CATER",
"id":null,
"name":"Catering"
}
]
Schema
BudgetCategory
| Name | Type | Format | Description |
|---|---|---|---|
description |
string |
- | The friendly name for this category. |
expenseTypes |
array |
expenseType |
Required The list of expense types that this budget category matches. |
name |
string |
- | Required The admin-facing name for this category. |
statusType |
string |
- | The status of this budget category. Supported values: OPEN, REMOVED |
id |
string |
- | The unique identifier for the budget category. |
ExpenseType
| Name | Type | Format | Description |
|---|---|---|---|
featureTypeCode |
string |
- | Required The type of feature that this expense type applies to: Purchase Request, Payment Request (Invoice), Expense, or Travel Authorization. Supported values: PURCHASE_REQUEST, PAYMENT_REQUEST, EXPENSE, REQUEST |
expenseTypeCode |
string |
- | Required The alphanumeric code that describes an expense type (Example: MEALS, AC_CATER). Any string may be used, but only expense type codes returned by GET /budgetCategory/expenseType will behave properly in the SAP Concur UI. |
name |
string |
- | READ ONLY The name for this expense type if it maps to an expense type set up in SAP Concur. |
id |
string |
- | The budget service's key for this object. If this field is not supplied, the service will use an existing expense type entry if one exists. |
Error Response
| Name | Type | Format | Description |
|---|---|---|---|
status |
boolean |
- | False if there was an error. |
errorMessageList |
array |
errorMessage |
List of all errors detected. |
Error Message
| Name | Type | Format | Description |
|---|---|---|---|
errorType |
String |
- | WARNING or ERROR. |
errorCode |
String |
- | Text code for this error. |
errorMessage |
String |
- | Plain language error message. |
Response Headers
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7231 Allow
- RFC 7234 Cache-Control
- RFC 7230 Content-Length
- RFC 7231 Content-Type
- RFC 7231 Date
- RFC 7234 Expires
- RFC 7232 ETag
- RFC 7234 Pragma
- RFC 7231 Server
- RFC 7231 Vary
Budget v4 - Budget Item
This resource is used to retrieve and update information about a budget that spans a single fiscal year. Each budget has multiple details that correspond to fiscal periods - months, quarters, or a single period for a yearly budget.
- GET All Budget Items
- GET a Budget Item
- POST a Budget Item
- DELETE a Budget Item
- Schema
- Response Headers
GET All Budget Items
Retrieve all budget items in groups of up to 50 items. Due to response size and performance considerations, this endpoint does not return budgetItemDetails. Use the GET a Budget Item to retrieve all the details for a single budget.
Scopes
This API call requires one of the following scopes:
budgetitem.read- Refer to Scope Usage for full details.budgetitem.write- Refer to Scope Usage for full details.
Request
URI
Template
GET /budget/v4/budgetItemHeader
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
adminView |
boolean |
query |
If true, returns all budgets for this entity, if false, returns only the budgets owned by the current user. Default: false |
offset |
integer |
query |
The start of the page offset. Default: 0 |
Headers
Response
Status Codes
- 200 OK Successful call, response is in body.
- 400 Bad Request The request was determined to be invalid by the server.
- 403 Forbidden The user does not have the necessary permissions to perform the request.
- 500 Internal Server Error Error message in response body.
- 504 Gateway Timeout Error message in response body.
Headers
Payload
Example
Request
GET https://us.api.concursolutions.com/budget/v4/budgetItemHeader
Authorization: Bearer {token}
Accept: application/json
Response
HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 1270
concur-correlationid: dd6cee88-b725-4c06-9ee9-0ca4ae4f16b2
{
"totalRows":122,"offset":0,"limit":50,
"budgetItemHeaders":[
{
"name":"Marketing-US-Jean Normandy",
"isTest":false,
"budgetItemStatusType":"OPEN",
"description":"Marketing-US",
"id":"72eee673-3d81-49c2-966a-b63c7a9302e6",
"costObjects":[
{
"code": "6",
"fieldDefinitionId": "86eee673-3d81-49c2-966a-b63c7a9302e2",
"value": "2",
"listKey": "1334",
"operator": "EQUAL",
"displayName": "Country Code"
}
],
"periodType":"YEARLY",
"active":true,
"owned":false,
"budgetAmounts":{
"pendingAmount":1178.37697091,
"unExpensedAmount":2310.73578092,
"spendAmount":35.78378912,
"adjustedBudgetAmount": 0,
"availableAmount":8785.83923997,
"unExpensedSettings":null,
"threshold":"UNDER",
"consumedPercent":12
},
"createdDate": "2019-06-26T17:49:53.102Z",
"budgetItemHeaderId":"72eee673-3d81-49c2-966a-b63c7a9302e6",
"budgetName":"Marketing-US-Jean Normandy",
"currencyCode":"EUR",
"annualBudget":10000.00000000,
"budgetCategory":{
"name":"airfare",
"description":null,
"statusType":"OPEN",
"id":"27451c2d-9121-44bd-b4b0-f2119d2071c7"
},
"owner":{
"externalUserCUUID":"8002250890004822936",
"employeeUuid":"210fe25f-e326-495c-847a-de333173f616",
"id":"f779261d-77ce-4123-b739-d842ef6f104d",
"name":"Jean Normandy",
"email":"jean.normandy@xyz.com",
"employeeId":"jean.normandy"
},
"budgetApprovers":[
{
"externalUserCUUID":"8002250890004822936",
"employeeUuid":"210fe25f-e326-495c-847a-de333173f616",
"id":"f779261d-77ce-4123-b739-d842ef6f104d",
"name":"Jean Normandy",
"email":"jean.normandy@xyz.com",
"employeeId":"jean.normandy"
}
],
"budgetManagers":[
{
"externalUserCUUID":"1563846384638464842",
"employeeUuid":"13a13839-68d6-4ee8-90e9-58604278aa8f",
"id":"e2bae688-e000-464a-8728-e1362c94f172",
"name":"Walter Gupta",
"email":"walter.gupta@xyz.com",
"employeeId":"walter.gupta"
}
],
"budgetType": "PERSONAL_USE",
"budgetViewers":[
{
"externalUserCUUID":"5005380230004873464",
"employeeUuid":"eb6082b0-3a9a-4e79-a350-e6e067f34969",
"id":"7ce7dfe0-6168-4b93-bb35-386bf023acc6",
"name":"Dan Lee",
"email":"dan.lee@xyz.com",
"employeeId":"dan.lee"
}
],
"dateRange": null,
"fiscalYear":{
"name":"2017",
"displayName":"2017",
"startDate":"2017-01-01",
"endDate":"2017-12-31",
"status":"OPEN",
"id":"a4f9d57f-14ac-4f03-b5aa-4256e5cff790",
"lastModified":"2017-03-26 20:53:19",
"currentYear":false
}
},
{"Additional budget item headers removed for brevity":"Additional budget items headers removed for brevity"}
],
"href":"https://us.api.concursolutions.com/budget/v1.1/budgetItemHeader/?offset=0",
"next":{
"href":"http://budget-service-rqa3-budget.us-west-2.nonprod.cnqr.delivery/budget/v1.1/budgetItemHeader/?adminView=true&offset=50"
},
"previous":null
}
GET a Budget Item
Retrieve the details of a single budget item.
Scopes
This API call requires one of the following scopes:
budgetitem.read- Refer to Scope Usage for full details.budgetitem.write- Refer to Scope Usage for full details.
Request
URI
Template
GET /budget/v4/budgetItemHeader/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
uuid |
The budget item header's key field. |
Headers
Response
Status Codes
- 200 OK Successful call, response is in body.
- 400 Bad Request The request was determined to be invalid by the server.
- 403 Forbidden The user does not have the necessary permissions to perform the request.
- 404 Not Found The resource could not be found or does not exist.
- 500 Internal Server Error Error message in response body.
- 504 Gateway Timeout Error message in response body.
Headers
Payload
Example
Request
GET https://us.api.concursolutions.com/budget/v4/budgetItemHeader/72eee673-3d81-49c2-966a-b63c7a9302e6
Authorization: Bearer {token}
Response
HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 1270
concur-correlationid: 918cfb55-06a1-47da-8ef1-774a45427af9
{
"name":"Marketing-US-Jean Normandy",
"isTest":false,
"budgetItemStatusType":"OPEN",
"description":"Marketing-US",
"id":"72eee673-3d81-49c2-966a-b63c7a9302e6",
"costObjects":[
{
"code": "6",
"fieldDefinitionId": "86eee673-3d81-49c2-966a-b63c7a9302e2",
"value": "2",
"listKey": "1334",
"operator": "EQUAL",
"displayName": "Country Code"
}
],
"periodType":"QUARTERLY",
"active":true,
"owned":false,
"budgetAmounts":{
"pendingAmount":6870.48165307,
"unExpensedAmount":102126.89000000,
"spendAmount":764.86966050,
"adjustedBudgetAmount": 0,
"availableAmount":2364.64868643,
"unExpensedSettings":null,
"threshold":"UNDER",
"consumedPercent":76
},
"createdDate": "2019-06-26T17:49:53.102Z",
"currencyCode":"EUR",
"annualBudget":10000.00000000,
"budgetCategory":null,
"owner":{
"externalUserCUUID":"8002250890004822936",
"employeeUuid":"210fe25f-e326-495c-847a-de333173f616",
"id":"f779261d-77ce-4123-b739-d842ef6f104d",
"name":"Jean Normandy",
"email":"jean.normandy@xyz.com",
"employeeId":"jean.normandy"
},
"budgetApprovers":[
{
"externalUserCUUID":"8002250890004822936",
"employeeUuid":"210fe25f-e326-495c-847a-de333173f616",
"id":"f779261d-77ce-4123-b739-d842ef6f104d",
"name":"Jean Normandy",
"email":"jean.normandy@xyz.com",
"employeeId":"jean.normandy"
}
],
"budgetManagers":[
{
"externalUserCUUID":"1563846384638464842",
"employeeUuid":"13a13839-68d6-4ee8-90e9-58604278aa8f",
"id":"e2bae688-e000-464a-8728-e1362c94f172",
"name":"Walter Gupta",
"email":"walter.gupta@xyz.com",
"employeeId":"walter.gupta"
}
],
"budgetType": "PERSONAL_USE",
"budgetViewers":[
{
"externalUserCUUID":"5005380230004873464",
"employeeUuid":"eb6082b0-3a9a-4e79-a350-e6e067f34969",
"id":"7ce7dfe0-6168-4b93-bb35-386bf023acc6",
"name":"Dan Lee",
"email":"dan.lee@xyz.com",
"employeeId":"dan.lee"
}
],
"budgetItemDetails":[
{
"budgetItemHeaderId":"72eee673-3d81-49c2-966a-b63c7a9302e6",
"budgetName":"Marketing-US-Jean Normandy",
"currencyCode":"USD",
"amount":2500.00000000,
"id":"4c165d40-804f-4aaa-b900-a46538537f6a",
"budgetItemDetailStatusType":"OPEN",
"budgetAmounts":{
"pendingAmount":6870.48165307,
"unExpensedAmount":102126.89000000,
"spendAmount":764.86966050,
"adjustedBudgetAmount": 0,
"availableAmount":-5135.35131357,
"unExpensedSettings":null,
"consumedPercent":305,
"threshold":"OVER"
},
"detailDashboardBudgetItemAdjustmentDTOs": [
{
"adjustmentType": "BUDGET_BALANCE",
"amount": 0,
"amountType": "QUICK_EXPENSE",
"description": "string",
"transactionDate": "2019-06-26"
}
],
"fiscalPeriod":{
"name":"2017 - Q1",
"fiscalPeriodStatus":"OPEN",
"id":"b9659f8a-4e74-4531-9e23-1222ab1507f2",
"periodType":"QUARTERLY",
"startDate":"2017-01-01",
"endDate":"2017-03-31",
"spendDate":null,
"fiscalYearId":"bcb41c95-2d53-4a1a-830f-7c6b01fa79da",
"currentPeriod":false
},
"budgetItemBalances":[
{
"featureTypeCode":"PURCHASE_REQUEST",
"featureTypeSubCode":"NONE",
"workflowState":"SUBMITTED",
"amount":6870.48165307,
"id":"11cb732e-cbc4-41cb-82be-162d632d5499"
},
{
"featureTypeCode":"EXPENSE",
"featureTypeSubCode":"NONE",
"workflowState":"PAID",
"amount":764.86966050,
"id":"0f09cc65-b879-4969-a8a1-9dd52c96486d"
},
{
"featureTypeCode":"EXPENSE",
"featureTypeSubCode":"ERECEIPTS",
"workflowState":"UNSUBMITTED",
"amount":102126.89000000,
"id":"27c49c8a-c24d-42eb-b089-84268350ae03"
}
]
},
{
"budgetItemHeaderId":"72eee673-3d81-49c2-966a-b63c7a9302e6",
"budgetName":"Marketing-US-Jean Normandy",
"currencyCode":"EUR",
"amount":2500.00000000,
"id":"0a2dc181-389e-4c85-bb57-e4f1a11ace4e",
"budgetItemDetailStatusType":"OPEN",
"budgetAmounts":{
"pendingAmount":0,
"unExpensedAmount":0,
"spendAmount":0,
"adjustedBudgetAmount": 0,
"availableAmount":2500.00000000,
"unExpensedSettings":null,
"consumedPercent":0,
"threshold":"UNDER"
},
"detailDashboardBudgetItemAdjustmentDTOs": [
{
"adjustmentType": "BUDGET_BALANCE",
"amount": 0,
"amountType": "QUICK_EXPENSE",
"description": "string",
"transactionDate": "2019-06-26"
}
],
"fiscalPeriod":{
"name":"2017 - Q2",
"fiscalPeriodStatus":"OPEN",
"id":"590d4e22-40be-43cc-ac1b-01b0d0263e19",
"periodType":"QUARTERLY",
"startDate":"2017-04-01",
"endDate":"2017-06-30",
"spendDate":null,
"fiscalYearId":"bcb41c95-2d53-4a1a-830f-7c6b01fa79da",
"currentPeriod":true
},
"budgetItemBalances":[]
},
{
"Additional budget item details removed for brevity": "Additional budget item details removed for brevity"
}
],
"dateRange": null,
"fiscalYear":{
"name":"2017",
"displayName":"2017",
"startDate":"2017-01-01",
"endDate":"2017-12-31",
"status":"OPEN",
"id":"a4f9d57f-14ac-4f03-b5aa-4256e5cff790",
"lastModified":"2017-03-26 20:53:19",
"currentYear":false,
"monthlyFiscalPeriods":[
{
"name":"2017-Special - Jan",
"fiscalPeriodStatus":"OPEN",
"periodType":"MONTHLY",
"startDate":"2017-01-01",
"endDate":"2017-01-31",
"id":"1929d1d9-6c99-4635-9272-508364193f8f",
"spendDate":null,
"fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
"currentPeriod":false
},
{
"name":"2017-Special - Feb",
"fiscalPeriodStatus":"OPEN",
"periodType":"MONTHLY",
"startDate":"2017-02-01",
"endDate":"2017-02-28",
"id":"41aa7452-e52a-4fd6-9c8a-5b199edeadaf",
"spendDate":null,
"fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
"currentPeriod":false
},
{
"name":"2017-Special - Mar",
"fiscalPeriodStatus":"OPEN",
"periodType":"MONTHLY",
"startDate":"2017-03-01",
"endDate":"2017-03-31",
"id":"6c7d0b13-96b9-4d76-a083-4d38c96144e2",
"spendDate":null,
"fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
"currentPeriod":false
}
],
"quarterlyFiscalPeriods":[
{
"name":"2017-Special - Q1",
"fiscalPeriodStatus":"OPEN",
"id":"5ce25dfd-8b2b-4fea-91eb-f8f9ad0bb896 ",
"periodType":"QUARTERLY",
"startDate":"2017-01-01",
"endDate":"2017-03-31",
"spendDate":null,
"fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
"currentPeriod":false
},
{
"name":"2017-Special - Q2",
"fiscalPeriodStatus":"OPEN",
"id":"5ce25dfd-8b2b-4fea-91eb-f8f9ad0bb896 ",
"periodType":"QUARTERLY",
"startDate":"2017-04-01",
"endDate":"2017-06-30",
"spendDate":null,
"fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
"currentPeriod":false
},
{
"name":"2017-Special - Q3",
"fiscalPeriodStatus":"OPEN",
"id":"5ce25dfd-8b2b-4fea-91eb-f8f9ad0bb896 ",
"periodType":"QUARTERLY",
"startDate":"2017-07-01",
"endDate":"2017-09-30",
"spendDate":null,
"fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
"currentPeriod":false
},
{
"name":"2017-Special - Q4",
"fiscalPeriodStatus":"OPEN",
"id":"5ce25dfd-8b2b-4fea-91eb-f8f9ad0bb896 ",
"periodType":"QUARTERLY",
"startDate":"2017-10-01",
"endDate":"2017-12-31",
"spendDate":null,
"fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
"currentPeriod":false
}
],
"yearlyFiscalPeriods":[
{
"name":"2017-Special",
"fiscalPeriodStatus":"OPEN",
"id":"a6bede66-4f3d-412f-a620-2a073013cb2a",
"periodType":"YEARLY",
"startDate":"2017-01-01",
"endDate":"2017-12-31",
"spendDate":null,
"fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
"currentPeriod":false
}
],
"customFiscalPeriods":[],
}
}
POST a Budget Item
Save a new budget or update an existing budget.
Scopes
budgetitem.write - Refer to Scope Usage for full details.
Request
URI
Template
POST /budget/v4/budgetItemHeader
Parameters
N/A
Headers
Payload
Response
Status Codes
- 200 OK Successful call, response is in body.
- 400 Bad Request The request was determined to be invalid by the server. Possibly a validation failed on the data that was sent in the payload. The response will have a list of validation errors in the body. See below for an example 400 response.
- 403 Forbidden The user does not have the necessary permissions to perform the request.
- 404 Not Found The resource could not be found or does not exist.
- 500 Internal Server Error Error message in response body.
- 504 Gateway Timeout Error message in response body.
Headers
Payload
Budget Item Response or Error Response
Example
Request
POST https://us.api.concursolutions.com/budget/v4/budgetItemHeader
Authorization: Bearer {token}
Quarterly Budget Example
{
"name":"Marketing-US-Jean Normandy",
"isTest":false,
"budgetItemStatusType":"OPEN",
"description":"Marketing-US",
"id":"72eee673-3d81-49c2-966a-b63c7a9302e6",
"costObjects":[
{
"fieldDefinitionId":"86eee673-3d81-49c2-966a-b63c7a9302e2",
"code": "6",
"value": "2",
"listKey": "1334",
"operator": "EQUAL",
"displayName":"Country Code"
}
],
"periodType":"QUARTERLY",
"currencyCode":"EUR",
"budgetCategory":{
"id":"27451c2d-9121-44bd-b4b0-f2119d2071c7"
},
"owner":{
"externalUserCUUID":"8002250890004822936",
"employeeUuid":"210fe25f-e326-495c-847a-de333173f616",
"email":"jean.normandy@xyz.com",
"employeeId":"jean.normandy"
},
"budgetApprovers":[
{
"externalUserCUUID":"5005380230004873464",
"employeeUuid":"eb6082b0-3a9a-4e79-a350-e6e067f34969",
"email":"dan.lee@xyz.com",
"employeeId":"dan.lee"
}
],
"budgetManagers":[
{
"externalUserCUUID":"1563846384638464842",
"employeeUuid":"13a13839-68d6-4ee8-90e9-58604278aa8f",
"email":"walter.gupta@xyz.com",
"employeeId":"walter.gupta"
}
],
"budgetType": "PERSONAL_USE",
"budgetViewers":[
{
"externalUserCUUID":"5005380230004873464",
"employeeUuid":"eb6082b0-3a9a-4e79-a350-e6e067f34969",
"email":"dan.lee@xyz.com",
"employeeId":"dan.lee"
}
],
"budgetItemDetails":[
{
"budgetItemHeaderId":"72eee673-3d81-49c2-966a-b63c7a9302e6",
"budgetName":"Marketing-US-Jean Normandy",
"currencyCode":"EUR",
"amount":2500.00000000,
"id":"4c165d40-804f-4aaa-b900-a46538537f6a",
"budgetItemDetailStatusType":"OPEN",
"fiscalPeriod":{
"id":"b9659f8a-4e74-4531-9e23-1222ab1507f2"
}
},
{
"budgetItemHeaderId":"72eee673-3d81-49c2-966a-b63c7a9302e6",
"budgetName":"Marketing-US-Jean Normandy",
"currencyCode":"EUR",
"amount":2500.00000000,
"id":"0a2dc181-389e-4c85-bb57-e4f1a11ace4e",
"budgetItemDetailStatusType":"OPEN",
"fiscalPeriod":{
"id":"590d4e22-40be-43cc-ac1b-01b0d0263e19"
}
},
{
"budgetItemHeaderId":"72eee673-3d81-49c2-966a-b63c7a9302e6",
"budgetName":"Marketing-US-Jean Normandy",
"currencyCode":"EUR",
"amount":2500.00000000,
"id":"35d7dc8a-5ec8-4d5f-ba7c-d9304f7afee3",
"budgetItemDetailStatusType":"OPEN",
"fiscalPeriod":{
"id":"09cd5be1-a21d-47f2-b6b5-8d9019709327"
}
},
{
"budgetItemHeaderId":"72eee673-3d81-49c2-966a-b63c7a9302e6",
"budgetName":"Marketing-US-Jean Normandy",
"currencyCode":"EUR",
"amount":2500.00000000,
"id":"4ec30f7c-e7fa-4832-9134-85bed9a85b9c",
"budgetItemDetailStatusType":"OPEN",
"fiscalPeriod":{
"id":"c3beec03-a096-4a33-b7af-b49127742702"
}
}
],
"fiscalYear":{
"id":"a4f9d57f-14ac-4f03-b5aa-4256e5cff790"
}
}
Date Range Budget Example
{
"name":"Marketing-US-Jean Normandy Date Range",
"isTest":false,
"budgetItemStatusType":"OPEN",
"description":"Marketing-US",
"id":"72eee673-3d81-49c2-966a-b63c7a9302e6",
"costObjects":[
{
"code": "6",
"fieldDefinitionId": "86eee673-3d81-49c2-966a-b63c7a9302e2",
"value": "2",
"listKey": "1334",
"operator": "EQUAL",
"displayName": "Country Code"
}
],
"periodType":"DATE_RANGE",
"currencyCode":"EUR",
"budgetCategory":{
"id":"27451c2d-9121-44bd-b4b0-f2119d2071c7"
},
"owner":{
"externalUserCUUID":"8002250890004822936",
"employeeUuid":"210fe25f-e326-495c-847a-de333173f616",
"email":"jean.normandy@xyz.com",
"employeeId":"jean.normandy"
},
"budgetApprovers":[
{
"externalUserCUUID":"5005380230004873464",
"employeeUuid":"eb6082b0-3a9a-4e79-a350-e6e067f34969",
"email":"dan.lee@xyz.com",
"employeeId":"dan.lee"
}
],
"budgetManagers":[
{
"externalUserCUUID":"1563846384638464842",
"employeeUuid":"13a13839-68d6-4ee8-90e9-58604278aa8f",
"email":"walter.gupta@xyz.com",
"employeeId":"walter.gupta"
}
],
"budgetType": "PERSONAL_USE",
"budgetViewers":[
{
"externalUserCUUID":"5005380230004873464",
"employeeUuid":"eb6082b0-3a9a-4e79-a350-e6e067f34969",
"email":"dan.lee@xyz.com",
"employeeId":"dan.lee"
}
],
"budgetItemDetails":[
{
"budgetItemHeaderId":"72eee673-3d81-49c2-966a-b63c7a9302e6",
"budgetName":"Marketing-US-Jean Normandy",
"currencyCode":"EUR",
"amount":2500.00000000,
"id":"4c165d40-804f-4aaa-b900-a46538537f6a",
"budgetItemDetailStatusType":"OPEN",
"fiscalPeriod":{
"id":"b9659f8a-4e74-4531-9e23-1222ab1507f7"
}
}
],
"fiscalYear":{
"id":null
}
}
Response
Success Response
HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 97
concur-correlationid: 809a0898-e523-4114-950d-bd22705a3b25
{
"success": true,
"budgetItemHeaderId": "72eee673-3d81-49c2-966a-b63c7a9302e6"
}
Failure Response
HTTP/1.1 400 Bad Request
Cache-Control: no-store
Connection: close
Content-Length: 459
Content-Type: application/json;charset=utf-8
Date: Fri, 21 Sep 2018 15:27:05 GMT
Expires: Thu, 20 Sep 2018 15:27:05 GMT
Pragma: no-cache
concur-correlationid: cea62849-02e5-4a7f-a576-68280c84bd02
{
"status" : false,
"errorMessageList" : [
{
"errorType" : "ERROR",
"errorCode" : "BUDGET.BUDGET_ITEM_NAME_REQUIRED",
"errorMessage" : "Budget item name is required"
},
{
"errorType" : "ERROR",
"errorCode" : "BUDGET.BUDGET_ITEM_NAME_ERROR",
"errorMessage" : "Budget item name should be more than 1 characters"
},
{
"errorType" : "ERROR",
"errorCode" : "BUDGET.BUDGET_ITEM_OWNER_REQUIRED",
"errorMessage" : "Budget item owner is required"
}
]
}
DELETE a Budget Item Header
Delete a budget item.
Scopes
budgetitem.write - Refer to Scope Usage for full details.
Request
URI
Template
DELETE /budget/v4/budgetItemHeader/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
The budget item header's key field. |
Headers
Response
Status Codes
- 200 OK Successful call, response is in body.
- 400 Bad Request The request was determined to be invalid by the server.
- 403 Forbidden The user does not have the necessary permissions to perform the request.
- 404 Not Found The resource could not be found or does not exist.
- 500 Internal Server Error Error message in response body.
- 504 Gateway Timeout Error message in response body.
Headers
Payload
Budget Item Response or Error Response
Example
Request
DELETE https://us.api.concursolutions.com/budget/v4/budgetItemHeader/72eee673-3d81-49c2-966a-b63c7a9302e6
Authorization: Bearer {token}
Response
HTTP/1.1 200 OK
Cache-Control: no-store
Connection: keep-alive
Content-Length: 97
Content-Type: application/json;charset=utf-8
Date: Fri, 21 Sep 2018 15:24:27 GMT
Expires: Thu, 20 Sep 2018 15:24:27 GMT
Pragma: no-cache
Vary: Origin
concur-correlationid: 86a0d9fe-9e98-43c3-89d8-a2917dd844cb
{
"success": true,
"budgetItemHeaderId": "72eee673-3d81-49c2-966a-b63c7a9302e6"
}
Schema
PagedBudgetItemHeaderList
| Name | Type | Format | Description |
|---|---|---|---|
totalRows |
integer |
- | The total number of rows available. |
offset |
integer |
- | The starting row for this page of results (zero-based). |
limit |
integer |
- | The number of results returned per page. Maximum: 50 |
budgetItemHeaders |
array |
budgetItemHeader |
List of budget item headers. Each budget item header represents a single budget for a fiscal year. |
href |
string |
- | The link to this page of results. |
previous |
string |
href |
The href for the previous page of results (null if this is the first page of results). |
next |
string |
href |
The href for the next page of results (null if no results remaining). |
BudgetItemHeader
| Name | Type | Format | Description |
|---|---|---|---|
active |
boolean |
- | READ ONLY Indicates if this budget should be displayed on user screens. |
annualBudget |
decimal |
- | READ ONLY The total budget amount and accumulated balances for this budget header. |
budgetAmounts |
array |
budgetAmounts |
READ ONLY The accumulated budget amounts for this budget. |
budgetManagers |
array |
budgetPerson |
If managers exist, spend items only matches this budget if one of the managers is in the manager hierarchy of the submitter or approver for the given spend item. |
budgetApprovers |
array |
budgetPerson |
The workflow approvers for this budget. |
budgetCategory |
array |
budgetCategory |
The budget category for this budget item. If a budget category is present, spending items must match one of the expense types in the budget category in order to match this budget. |
budgetItemDetails |
array |
budgetItemDetail |
Required Specify the budget information for each fiscal period in the fiscal year. |
budgetItemStatusType |
string |
- | The status of this budget item. Supported values: OPEN, CLOSED(no spending can be attached to this budget), REMOVED |
budgetType |
string |
- | The budget type indicates if the budget item is personal or not. Supported values: PERSONAL_USE, BUDGET, RESTRICTED |
budgetViewers |
array |
budgetPerson |
The users who can view this budget. |
costObjects |
array |
budgetTrackingValue |
The cost object list for matching spending items. |
createdDate |
date |
YYYY-MM-DD |
READ ONLY The time the budget item header was created. Date in UTC. |
currencyCode |
string |
- | The 3-letter ISO 4217 currency code for the budget currency. This is the currency code of the budget amount. Spending Items are converted using yesterday's closing value. Examples: USD - US dollars; BRL - Brazilian real; CAD - Canadian dollar; CHF - Swiss franc; EUR - Euro; GBO - Pound sterling; HKD - Hong Kong dollar; INR - Indian rupee; MXN - Mexican peso; NOK - Norwegian krone; SEK - Swedish krona. |
description |
string |
- | Required The user-friendly name for this budget. This description is displayed to end users on desktop and mobile. |
dateRange |
dateRange |
- | READ ONLY Specify custom date range for budget. |
fiscalYear |
array |
fiscalYear |
Required The fiscal year for this budget. Only the ID of the fiscal year, which can be retrieved from the Fiscal Year service, is required for creating/updating a budget. |
fiscalYearId |
string |
- | The unique identifier of the fiscal year for this budget. |
id |
string |
- | The key for this object. |
isTest |
boolean |
- | The test flag for the budget item. If true, this budget will only match spending submitted by test users. |
lastModifiedDate |
dateRange |
- | READ ONLY The last time the budget item header was updated. Date in UTC. |
name |
string |
- | Required The admin-facing name for this budget. |
owned |
string |
- | READ ONLY A flag indicating if the current user is the owner of this budget. |
owner |
array |
budgetPerson |
Required The user who is ultimately responsible for this budget. |
periodType |
string |
- | READ ONLY The type of period within the fiscal year that this budget's details use. |
BudgetItemDetail
| Name | Type | Format | Description |
|---|---|---|---|
amount |
decimal |
- | Required The budget currency amount allocated to this fiscal period. May be zero. |
budgetAmounts |
array |
budgetAmounts |
READ ONLY The accumulated budget numbers for this budget. |
budgetItemBalances |
array |
budgetItemBalance |
READ ONLY Shows the break-out of budget spending by product and workflow state. |
budgetItemDetailStatusType |
string |
- | The status of this budget item. Supported values: OPEN, CLOSED(no spending can be attached to this budget), REMOVED |
currencyCode |
string |
- | The 3-letter ISO 4217 currency code for the budget currency. Examples: USD - US dollars; BRL - Brazilian real; CAD - Canadian dollar; CHF - Swiss franc; EUR - Euro; GBO - Pound sterling; HKD - Hong Kong dollar; INR - Indian rupee; MXN - Mexican peso; NOK - Norwegian krone; SEK - Swedish krona. |
budgetName |
string |
- | READ ONLY The admin-facing name of this budget. |
budgetItemHeaderId |
string |
- | READ ONLY The unique ID of the header that contains this budget item detail. |
fiscalPeriod |
fiscalPeriod |
- | Required The fiscal period for this budget amount. Only the ID of the fiscal period, which can be retrieved from the Fiscal Year service, is required for creating/updating a budget. |
detailDashboardBudgetItemAdjustmentDTOs |
array |
detailDashboardBudgetItemAdjustment |
READ ONLY List of budget adjustments. |
fiscalPeriod |
array |
fiscalPeriod |
Required The specific fiscal period when this budget amount will be used. Only the ID of the fiscal period, which can be retrieved from the Fiscal Year service, is required for creating/updating a budget. |
BudgetAmounts
| Name | Type | Format | Description |
|---|---|---|---|
adjustedBudgetAmount |
decimal |
- | READ ONLY The amount adjusted against this budget. |
availableAmount |
decimal |
- | READ ONLY The available amount accumulated against this budget. Uses budget setting to determine which amounts are included to calculate available amount. |
consumedPercent |
decimal |
- | READ ONLY The percentage of the budget that is considered used. Uses budget setting to determine which amounts to include. |
pendingAmount |
decimal |
- | READ ONLY The pending amount accumulated against this budget. |
spendAmount |
decimal |
- | READ ONLY The spent amount accumulated against this budget. |
threshold |
string |
- | READ ONLY The indicator of whether this budget is under the alert limit, equal to or over the alert limit but under the control limit, or equal to or over the control limit. Supported values: UNDER, ALERT, OVER |
unExpensedAmount |
decimal |
- | READ ONLY The amount of unexpensed items like travel bookings, quick expenses, or e-receipts. |
unExpensedSettings |
string |
- | READ ONLY The company's budget setting for unexpensed items. Applies to all budgets for the company. Supported values: SHOW_UNSUBMITTED_EXPENSES_AS_PENDING, SHOW_UNSUBMITTED_EXPENSES_BALANCE, DO_NOT_SHOW_UNSUBMITTED_EXPENSES |
BudgetPerson
Provide externalUserCUUID or email or employee ID of the user for looking up the person.
| Name | Type | Format | Description |
|---|---|---|---|
externalUserCUUID |
string |
- | The unique identifier for this user. This must match the CUUID from the SAP Concur profile service. |
name |
string |
- | READ ONLY The user's name. Provided for convenience. |
id |
string |
- | The budget service's unique identifier for this user. |
email |
string |
- | The email address of the person to lookup. |
employeeId |
string |
- | READ ONLY The employee ID of the person to lookup. |
employeeUuid |
string |
- | The unique identifier for this user. This must match the UUID from the SAP Concur profile service. |
BudgetCategory
| Name | Type | Format | Description |
|---|---|---|---|
description |
string |
- | The list of expense types that this budget category matches. |
name |
string |
- | The admin-facing name for this category. |
statusType |
string |
- | The status of this budget category. Supported values: OPEN, REMOVED |
id |
string |
- | The unique identifier for the budget category. |
ExpenseType
| Name | Type | Format | Description |
|---|---|---|---|
featureTypeCode |
string |
- | Required The product that this expense type applies to: Purchase Request, Invoice (Payment Request), Expense, or Request. Supported values: PURCHASE_REQUEST, PAYMENT_REQUEST, EXPENSE, REQUEST |
expenseTypeCode |
string |
- | Required The alphanumeric code that describes an expense type. (Example: MEALS, AC_CATER) Valid expense type codes are returned by the GET /budgetCategory/expenseType method described in the Budget Category service. |
name |
string |
- | READ ONLY The name for this expense type if it maps to an expense type set up in your SAP Concur product(s). |
id |
string |
- | The budget service's key for this object. |
BudgetTrackingValue
| Name | Type | Format | Description |
|---|---|---|---|
code |
string |
- | The code for the cost object field. This can be used instead of fieldDefinitionId and will take priority if populated. This value can be found for your budget tracking fields you have configured by using the GET All Budget Tracking Fields resource. |
value |
string |
- | The value for the cost object field. The value of this field will be ignored unless the operator field is EQUAL, NOTEQUAL, INLIST, or NOTINLIST. The value of this field can be one or more comma-separated values if the INLIST or NOTINLIST operator is chosen. |
listKey |
string |
- | When setting up the budget, specify the listKey that maps to the value of this list in the SAP Concur list service. |
operator |
string |
- | Required The comparison to use when matching values for this tracking field. Supported values: EQUAL, INLIST, ISBLANK, NOTEQUAL, NOTINLIST, ISNOTBLANK, ISTRUE, ISFALSE, ISNOTTRUE, ISNOTFALSE |
fieldDefinitionID |
string |
- | Required The budget service’s key for this object’s field definition ID. This value can be found for your budget tracking fields you have configured by using the GET All Budget TrackingFields resource. |
displayName |
string |
- | The budget field tracking name. |
BudgetItemBalance
| Name | Type | Format | Description |
|---|---|---|---|
amount |
decimal |
- | READ ONLY The balance amount. |
featureTypeCode |
string |
- | READ ONLY The product type for this balance. Supported values: REQUEST, TRAVEL, EXPENSE, PAYMENT_REQUEST |
featureTypeSubCode |
string |
- | READ ONLY The feature type sub code for this balance. Supported values: QUICK_EXPENSE, ERECEIPT, CREDIT_CARD, PERSONAL_CARD, TRIP, RECEIPT_CAPTURE, BILLING_STATEMENT, MANUAL, NONE, BUDGET_AMOUNT, SPENT_AMOUNT, PENDING_AMOUNT, PRE_AUTHORIZED, PURGE_ADJUSTMENT |
workflowState |
string |
- | READ ONLY Supported values: UNSUBMITTED, UNSUBMITTED_HELD, SUBMITTED, APPROVED, PROCESSED, PAID. |
id |
string |
- | The unique identifier for this particular budget balance bucket.. |
FiscalYear
| Name | Type | Format | Description |
|---|---|---|---|
currentYear |
boolean |
- | READ ONLY If true, this is the current fiscal year based on the current date and time. false, if otherwise. |
startDate |
date |
YYYY-MM-DD |
Required The start date for this fiscal year. The distance between start date and end date may not be more than two years. |
endDate |
date |
YYYY-MM-DD |
Required The end date for this fiscal year. The distance between start date and end date may not be more than two years. |
name |
datetime |
- | Required The name of this fiscal year. Must be unique for this entity. |
status |
string |
- | Required The status of this fiscal year. Supported values: OPEN, CLOSED, REMOVED |
id |
string |
- | The budget service's key for this object. |
lastModified |
datetime |
- | READ ONLY The UTC date and time when this object was last changed. |
displayName |
string |
- | READ ONLY Display name for fiscal year. For date range budget item we use this field to display. |
monthlyFiscalPeriods |
array |
fiscalPeriod |
READ ONLY The list of monthly Fiscal Periods in this Fiscal Year. Fiscal periods must complete fill the parent Fiscal Year with no overlaps. |
quarterlyFiscalPeriods |
array |
fiscalPeriod |
READ ONLY The list of quarterly Fiscal Periods in this Fiscal Year. If this parameter is not specified, quarterly Fiscal Periods are automatically generated based on the monthly Fiscal Periods supplied. |
yearlyFiscalPeriods |
array |
fiscalPeriod |
READ ONLY The list of yearly Fiscal Periods in this Fiscal Year. If this parameter is not specified, one period is created that fills the Fiscal Year. |
customFiscalPeriods |
array |
fiscalPeriod |
READ ONLY The list of custom Fiscal Periods in this Fiscal Year. Custom Fiscal Periods are API-only and will not display on user budget dashboards. |
openAndClosedFiscalPeriods |
array |
fiscalPeriod |
READ ONLY The list of all Fiscal Periods in this Fiscal Year, sorted by status. |
fiscalPeriods |
array |
fiscalPeriod |
READ ONLY The list of all Fiscal Periods in this Fiscal Year. |
displayName |
string |
- | READ ONLY Display name for fiscal year. For date range budget item we use this field to display. |
FiscalPeriod
| Name | Type | Format | Description |
|---|---|---|---|
currentPeriod |
boolean |
- | READ ONLY If true, this is the current fiscal period based on the current time. false, if otherwise. |
startDate |
date |
YYYY-MM-DD |
Required The start date for this fiscal period. Must be within the parent fiscal year. |
endDate |
date |
YYYY-MM-DD |
Required The end date for this fiscal year. Must be within the parent fiscal year. |
name |
string |
- | Required The name of this fiscal period. Must be unique for this entity. |
fiscalPeriodStatus |
string |
- | Required The status of this fiscal period. Supported values: OPEN, CLOSED, REMOVED |
periodType |
string |
- | Required The type of fiscal period. Supported values: MONTHLY, QUARTERLY, YEARLY, CUSTOM, DATE_RANGE |
fiscalYearId |
string |
- | The key of the parent fiscal year for this fiscal period. |
id |
string |
- | The budget service's key for this object. |
spendDate |
date |
- | READ ONLY If the current date is after this fiscal period's start date, this field shows the current date. |
DateRange
| Name | Type | Format | Description |
|---|---|---|---|
startDate |
date |
YYYY-MM-DD |
The start date for the budget. |
endDate |
date |
YYYY-MM-DD |
The end date for the budget. |
DetailDashboardBudgetItemAdjustment
| Name | Type | Format | Description |
|---|---|---|---|
adjustmentType |
string |
- | The type of adjustment being made. Only a user reference field. Supported values: BUDGET_BALANCE, FUND_TRANSFER, EXPENSE, PAYMENT_REQUEST, PURCHASE_REQUEST, REQUEST, PURGE_ADJUSTMENT |
amount |
decimal |
- | The value of the amount adjusted (+/-). |
amountType |
string |
- | The amount type of the field. Supported values: QUICK_EXPENSE, ERECEIPT, CREDIT_CARD, PERSONAL_CARD, TRIP, RECEIPT_CAPTURE, BILLING_STATEMENT, MANUAL, NONE, BUDGET_AMOUNT, SPENT_AMOUNT, PENDING_AMOUNT, PRE_AUTHORIZED, PURGE_ADJUSTMENT |
description |
string |
- | The short description of the adjustment. |
transactionDate |
date |
YYYY-MM-DD |
The transaction date of adjusted spend. Required when the adjustment is made for amount type. Supported values: SPENT_AMOUNT, PENDING_AMOUNT |
BudgetItemResponse
| Name | Type | Format | Description |
|---|---|---|---|
success |
boolean |
- | True or False for success or failure. |
budgetItemHeaderId |
guid |
- | The key of the created/updated/removed budget item header. |
Error Response
| Name | Type | Format | Description |
|---|---|---|---|
status |
boolean |
- | False if there was an error. |
errorMessageList |
array |
errorMessage |
List of all errors detected. |
Error Message
| Name | Type | Format | Description |
|---|---|---|---|
errorType |
String |
- | WARNING or ERROR. |
errorCode |
String |
- | Text code for this error. |
errorMessage |
String |
- | Plain language error message. |
Response Headers
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7231 Allow
- RFC 7234 Cache-Control
- RFC 7230 Content-Length
- RFC 7231 Content-Type
- RFC 7231 Date
- RFC 7234 Expires
- RFC 7232 ETag
- RFC 7234 Pragma
- RFC 7231 Server
- RFC 7231 Vary
Budget v4 - Budget Tracking
This resource is used to retrieve information about Budget's tracking fields for an entity. Every entity may have a specific set of budget tracking fields and every budget may enable any or all of the budget tracking fields. If there are tracking fields associated, the budgets get matched to the product only when the tracking field conditions are met.
GET All Budget Tracking Fields
Retrieve budget tracking fields information that is setup in budget configuration. This information returned here like the field definition ID, is needed if you will be importing budgets with tracking field values using the post budget item resource.
Scopes
This API call requires one of the following scopes:
budgetitem.read- Refer to Scope Usage for full details.budgetitem.write- Refer to Scope Usage for full details.
Request
URI
Template
GET /budget/v4/budgetTrackingField
Parameters
N/A
Headers
Response
Status Codes
- 200 OK Successful call, response is in body.
- 400 Bad Request The request was determined to be invalid by the server. Possibly a validation failed on the data that was sent in the payload. The response will have a list of validation errors in the body. See below for an example 400 response.
- 403 Forbidden The user does not have the necessary permissions to perform the request.
- 404 Not Found The resource could not be found or does not exist.
- 500 Internal Server Error Error message in response body.
- 504 Gateway Timeout Error message in response body.
Headers
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7231 Allow
- RFC 7234 Cache-Control
- RFC 7230 Content-Length
- RFC 7231 Content-Type
- RFC 7231 Date
- RFC 7234 Expires
- RFC 7232 ETag
- RFC 7234 Pragma
- RFC 7231 Server
- RFC 7231 Vary
Payload
Example
Request
GET https://us.api.concursolutions.com/budget/v4/budgetTrackingField
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json
Response
HTTP/1.1 200 OK
Cache-Control: no-store
Connection: keep-alive
Content-Length: 1371
Content-Type: application/json;charset=utf-8
Date: Fri, 21 Sep 2018 15:24:27 GMT
Expires: Thu, 20 Sep 2018 15:24:27 GMT
Pragma: no-cache
Vary: Origin
concur-correlationid: 86a0d9fe-9e98-43c3-89d8-a2917dd844cb
[
{
"budgetTrackingFieldName": "Cost Center",
"fieldType": "LIST",
"listSyncGuid": "8652CDF9C12B4051B8D180E20840CE9B",
"fieldId": "86309e0c-913c-47a5-9bcf-24a05342c718",
"budgetSequenceNumber": 2,
"connectedListSequenceNumber": 1,
"fieldDefinitionId":"19b07cff-4d36-44bd-acfe-befcfa607075"
},
{
"budgetTrackingFieldName": "Company",
"fieldType": "VARCHAR",
"listSyncGuid": null,
"fieldId": "d8f911a1-f298-4c65-b06b-710d482c9c46",
"budgetSequenceNumber": 1,
"connectedListSequenceNumber": 1,
"fieldDefinitionId":"ea2b82f3-ac18-4509-a748-842054f47f5f"
},
{
"budgetTrackingFieldName": "Department",
"fieldType": "LIST",
"listSyncGuid": "8652CDF9C12B4051B8D180E2084Q412",
"fieldId": "c4f721cb-8fc9-48cf-993e-5ea0edefcdbd",
"budgetSequenceNumber": 3,
"connectedListSequenceNumber": 1,
"fieldDefinitionId":"8b09cc4a-0274-4f2e-b223-3179f560c6bf"
},
{
"budgetTrackingFieldName": "Vendor",
"fieldType": "VARCHAR",
"listSyncGuid": null,
"fieldId": "bcc7ba39-a3a0-4267-84f4-1d5b439cce65",
"budgetSequenceNumber": 5,
"connectedListSequenceNumber": 1,
"fieldDefinitionId":"d543d38a-ef64-4585-8151-b2f909b7e2d3"
},
{
"budgetTrackingFieldName": "Region",
"fieldType": "MLIST",
"listSyncGuid": "8652CDF9C12B4051B8D180E20840CE9B",
"fieldId": "a2502b74-e3ce-4b30-a3a4-b6ceb68cf677",
"budgetSequenceNumber": 6,
"connectedListSequenceNumber": 1,
"fieldDefinitionId":"51c46189-110b-4de4-80ac-4cbae48625d6"
},
{
"budgetTrackingFieldName": "Country",
"fieldType": "VARCHAR",
"listSyncGuid": null,
"fieldId": "4ac122ad-8c0b-4076-bd41-49b09d576d5b",
"budgetSequenceNumber": 4,
"connectedListSequenceNumber": 1,
"fieldDefinitionId":"b5017eae-0b99-47df-8e0d-2f908292598a"
}
]
Schema
Budget Tracking Field
| Name | Type | Format | Description |
|---|---|---|---|
budgetTrackingFieldName |
string |
- | The budget field tracking name. |
fieldType |
string |
- | The data type of this field or field collection. Supported values: LIST, MLIST, VARCHAR |
listSyncGuid |
string |
- | If the dataType of this item is LIST or MLIST, this is the ID of the list definition from the SAP Concur list service. |
fieldId |
string |
- | The budget service's key for this object. |
budgetSequenceNumber |
integer |
- | The sequence or the order in which the budget tracking field appears in the budget UI. This value can be used instead of fieldDefinitionId when importing budgets with POST resource. The budgetSequenceNumber is the the same as the code field when importing budgets. |
connectedListSequenceNumber |
integer |
- | READ ONLY Indicates the level of the budget tracking field in a connected list. |
fieldDefinitionId |
string |
- | The budget service's key for this object's field definition ID. This value is required when using the Budget Item POST Resource to create or update a new budget using budget tracking fields. |
Budget v4 - Fiscal Year
The Fiscal Calendar is used both for Reporting and Budget. A fiscal year can start and end at any date as long as the end date is after the start date and does not span more than two years. Fiscal years cannot overlap. Fiscal periods cannot overlap and are limited to 24 per fiscal year.
GET All Fiscal Years
Retrieve a list of all fiscal years
- Use the
lastModifiedAfterparameter if you wish to only retrieve fiscal years that were changed after a certain date. - Use the
includeRemovedparameter if you wish to retrieve all fiscal years, including those that have been deleted. Important: deleted data that is beyond the configured retention period can not be returned.
Scopes
This API call requires one of the following scopes:
budgetitem.read- Refer to Scope Usage for full details.budgetitem.write- Refer to Scope Usage for full details.fiscalyear.read- Refer to Scope Usage for full details.fiscalyear.write- Refer to Scope Usage for full details.
Request
URI
Template
GET /budget/v4/fiscalYear
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
lastModifiedAfter |
datetime |
YYYY-MM-DDTHH:MM:SS |
Use this field if you only want Fiscal Years that were changed after the supplied date. The supplied date will be interpreted in the UTC time zone. If lastModifiedAfter is not supplied, the service will return all Fiscal Years, regardless of modified date. Example: 2016-03-29T16:12:20 |
includeRemoved |
boolean |
query |
If true, the service will return all Fiscal Years, including those that were previously removed. If not supplied, this field defaults to false. |
Headers
Response
Status Codes
- 200 OK Successful call, response is in body.
- 400 Bad Request The request was determined to be invalid by the server.
- 403 Forbidden The user does not have the necessary permissions to perform the request.
- 500 Internal Server Error Error message in response body.
- 504 Gateway Timeout Error message in response body.
Headers
Payload
Example
Request
GET https://us.api.concursolutions.com/budget/v4/fiscalYear?lastModifiedAfter=2017-02-27T12:30:00
Authorization: Bearer {token}
Content-Type: application/json
Response
HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 2187
concur-correlationid: ffa4ae0a-f65c-4037-8bfb-8996c3fca28c
[
{
"name":"2017",
"startDate":"2017-01-01",
"endDate":"2017-12-31",
"status":"OPEN",
"id":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
"lastModified":"2017-03-26 20:53:19",
"currentYear":false,
"monthlyFiscalPeriods":[
{
"name":"2017 - Aug",
"fiscalPeriodStatus":"OPEN",
"id":"a4e94128-c7b7-4561-a57e-1512e59e4896",
"periodType":"MONTHLY",
"startDate":"2017-08-01",
"endDate":"2017-08-31",
"spendDate":null,
"fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
"currentPeriod":false
},
{
"name":"2017 - Jan",
"fiscalPeriodStatus":"CLOSED",
"id":"ab2810f5-f045-45b0-b2b2-8e84bc978e27",
"periodType":"MONTHLY",
"startDate":"2017-01-01",
"endDate":"2017-01-30",
"spendDate":null,
"fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
"currentPeriod":false
},
{
"Additional fiscal periods removed for brevity": "Additional fiscal periods removed for brevity"
}
],
"quarterlyFiscalPeriods":[
{"name":"2017 - Q4",
"fiscalPeriodStatus":"OPEN",
"id":"655ffe9d-caca-4f2f-a4a1-e04cfb68fd6e",
"periodType":"QUARTERLY",
"startDate":"2017-10-01",
"endDate":"2017-12-31",
"spendDate":null,
"fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
"currentPeriod":false
},
{
"Additional fiscal periods removed for brevity": "Additional fiscal periods removed for brevity"
}
],
"yearlyFiscalPeriods":[
{
"name":"2017",
"fiscalPeriodStatus":"OPEN",
"id":"2fb8ea93-172a-47a6-9611-44eb75ad547b",
"periodType":"YEARLY",
"startDate":"2017-01-01",
"endDate":"2017-12-31",
"spendDate":null,
"fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
"currentPeriod":false
}
],
"customFiscalPeriods":[]
}
]
GET a Fiscal Year
Retrieve a single fiscal year by ID.
Scopes
This API call requires one of the following scopes:
budgetitem.read- Refer to Scope Usage for full details.budgetitem.write- Refer to Scope Usage for full details.fiscalyear.read- Refer to Scope Usage for full details.fiscalyear.write- Refer to Scope Usage for full details.
Request
URI
Template
GET /budget/v4/fiscalYear/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
uuid |
The fiscal year's key field. |
Headers
Response
Status Codes
- 200 OK Successful call, response is in body.
- 400 Bad Request The request was determined to be invalid by the server.
- 403 Forbidden The user does not have the necessary permissions to perform the request.
- 404 Not Found The resource could not be found or does not exist.
- 500 Internal Server Error Error message in response body.
- 504 Gateway Timeout Error message in response body.
Headers
Payload
Example
Request
GET https://us.api.concursolutions.com/budget/v4/fiscalYear/5e58b9b1-fed6-4d36-a5a1-a1ed325931d4
Authorization: Bearer {token}
Response
HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 1270
concur-correlationid: 39216840-2808-4c49-8874-e9862d96fdb6
{
"name":"2017",
"startDate":"2017-01-01",
"endDate":"2017-12-31",
"status":"OPEN",
"id":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
"lastModified":"2017-03-26 20:53:19",
"currentYear":false,
"monthlyFiscalPeriods":[
{
"name":"2017 - Aug",
"fiscalPeriodStatus":"OPEN",
"id":"a4e94128-c7b7-4561-a57e-1512e59e4896",
"periodType":"MONTHLY",
"startDate":"2017-08-01",
"endDate":"2017-08-31",
"spendDate":null,
"fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
"currentPeriod":false
},
{
"name":"2017 - Jan",
"fiscalPeriodStatus":"CLOSED",
"id":"ab2810f5-f045-45b0-b2b2-8e84bc978e27",
"periodType":"MONTHLY",
"startDate":"2017-01-01",
"endDate":"2017-01-30",
"spendDate":null,
"fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
"currentPeriod":false
},
{
"Additional fiscal periods removed for brevity": "Additional fiscal periods removed for brevity"
}
],
"quarterlyFiscalPeriods":[
{"name":"2017 - Q4",
"fiscalPeriodStatus":"OPEN",
"id":"655ffe9d-caca-4f2f-a4a1-e04cfb68fd6e",
"periodType":"QUARTERLY",
"startDate":"2017-10-01",
"endDate":"2017-12-31",
"spendDate":null,
"fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
"currentPeriod":false
},
{
"Additional fiscal periods removed for brevity": "Additional fiscal periods removed for brevity"
}
],
"yearlyFiscalPeriods":[
{
"name":"2017",
"fiscalPeriodStatus":"OPEN",
"id":"2fb8ea93-172a-47a6-9611-44eb75ad547b",
"periodType":"YEARLY",
"startDate":"2017-01-01",
"endDate":"2017-12-31",
"spendDate":null,
"fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
"currentPeriod":false
}
],
"customFiscalPeriods":[],
"displayName":"2017-Special"
}
POST Fiscal Year(s)
Create or update a list of one or more fiscal years.
- Fiscal years may be created for the future or the past
- Unless there is a need to do so, the client should only specify monthly fiscal periods when creating/updating a fiscal year. The system will auto-generate the quarterly and yearly fiscal periods.
Scopes
This API call requires one of the following scopes:
budgetitem.write- Refer to Scope Usage for full details.fiscalyear.write- Refer to Scope Usage for full details.
Request
URI
Template
POST /budget/v4/budgetCategory
Parameters
N/A
Headers
Payload
Response
Status Codes
- 200 OK Successful call, response is in body.
- 400 Bad Request The request was determined to be invalid by the server. Possibly a validation failed on the data that was sent in the payload. The response will have a list of validation errors in the body. See below for an example 400 response.
- 403 Forbidden The user does not have the necessary permissions to perform the request.
- 404 Not Found The resource could not be found or does not exist.
- 500 Internal Server Error Error message in response body.
- 504 Gateway Timeout Error message in response body.
Headers
Payload
Example
Request
POST https://us.api.concursolutions.com/budget/v4/fiscalYear
Authorization: Bearer {token}
[
{
"name":"2017-Special",
"startDate":"2017-01-01",
"endDate":"2017-03-31",
"status":"OPEN",
"monthlyFiscalPeriods":[
{
"name":"2017-Special - Jan",
"fiscalPeriodStatus":"OPEN",
"periodType":"MONTHLY",
"startDate":"2017-01-01",
"endDate":"2017-01-31"
},
{
"name":"2017-Special - Feb",
"fiscalPeriodStatus":"OPEN",
"periodType":"MONTHLY",
"startDate":"2017-02-01",
"endDate":"2017-02-28"
},
{
"name":"2017-Special - Mar",
"fiscalPeriodStatus":"OPEN",
"periodType":"MONTHLY",
"startDate":"2017-03-01",
"endDate":"2017-03-31"
}
],
"displayName":"2017-Special"
}
]
Response
Success Response
HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 1270
concur-correlationid: 5c00e59f-d00c-4019-8d3d-47130d8e37b4
[
{
"name":"2017-Special",
"startDate":"2017-01-01",
"endDate":"2017-03-31",
"status":"OPEN",
"id":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
"lastModified":"2018-03-26 20:54:11",
"currentYear":false,
"monthlyFiscalPeriods":[
{
"name":"2017-Special - Jan",
"fiscalPeriodStatus":"OPEN",
"periodType":"MONTHLY",
"startDate":"2017-01-01",
"endDate":"2017-01-31",
"id":"1929d1d9-6c99-4635-9272-508364193f8f",
"spendDate":null,
"fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
"currentPeriod":false
},
{
"name":"2017-Special - Feb",
"fiscalPeriodStatus":"OPEN",
"periodType":"MONTHLY",
"startDate":"2017-02-01",
"endDate":"2017-02-28",
"id":"41aa7452-e52a-4fd6-9c8a-5b199edeadaf",
"spendDate":null,
"fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
"currentPeriod":false
},
{
"name":"2017-Special - Mar",
"fiscalPeriodStatus":"OPEN",
"periodType":"MONTHLY",
"startDate":"2017-03-01",
"endDate":"2017-03-31",
"id":"6c7d0b13-96b9-4d76-a083-4d38c96144e2",
"spendDate":null,
"fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
"currentPeriod":false
}
],
"quarterlyFiscalPeriods":[
{
"name":"2017-Special - Q1",
"fiscalPeriodStatus":"OPEN",
"id":"5ce25dfd-8b2b-4fea-91eb-f8f9ad0bb896 ",
"periodType":"QUARTERLY",
"startDate":"2017-01-01",
"endDate":"2017-03-31",
"spendDate":null,
"fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
"currentPeriod":false
}
],
"yearlyFiscalPeriods":[
{
"name":"2017-Special",
"fiscalPeriodStatus":"OPEN",
"id":"a6bede66-4f3d-412f-a620-2a073013cb2a",
"periodType":"YEARLY",
"startDate":"2017-01-01",
"endDate":"2017-03-31",
"spendDate":null,
"fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
"currentPeriod":false
}
],
"customFiscalPeriods":[],
"displayName":"2017-Special"
}
]
Failure Response
HTTP/1.1 400 Bad Request
Cache-Control: no-store
Connection: close
Content-Length: 338
Content-Type: application/json;charset=utf-8
Date: Fri, 21 Sep 2018 15:27:05 GMT
Expires: Thu, 20 Sep 2018 15:27:05 GMT
Pragma: no-cache
concur-correlationid: cb061832-82eb-418e-a968-de6b4ce370ae
{
"status" : false,
"errorMessageList" : [
{
"errorType" : "ERROR",
"errorCode" : "BUDGET.FISCAL_YEAR_SDATE_ERROR",
"errorMessage" : "Fiscal year should have a start date"
},
{
"errorType" : "ERROR",
"errorCode" : "BUDGET.FISCAL_YEARS_HAVE_GAP",
"errorMessage" : "Fiscal years should not have gaps between them"
}
]
}
DELETE a Fiscal Year
Delete a fiscal year. Fiscal years that are in use may not be deleted.
Scopes
This API call requires one of the following scopes:
budgetitem.write- Refer to Scope Usage for full details.fiscalyear.write- Refer to Scope Usage for full details.
Request
URI
Template
DELETE /budget/v4/fiscalYear/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
uuid |
The fiscal years's key field. |
Headers
Response
Status Codes
- 200 OK Successful call, response is in body.
- 400 Bad Request The request was determined to be invalid by the server.
- 403 Forbidden The user does not have the necessary permissions to perform the request.
- 404 Not Found The resource could not be found or does not exist.
- 500 Internal Server Error Error message in response body.
- 504 Gateway Timeout Error message in response body.
Headers
Example
Request
DELETE https://us.api.concursolutions.com/budget/v4/fiscalYear/a11cfc7c-967f-415f-9b30-23f8ce2dbf69
Authorization: Bearer {token}
Response
HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 1270
concur-correlationid: eb7cf20a-3481-45a5-808c-98b8ef7fe805
Schema
FiscalYear
| Name | Type | Format | Description |
|---|---|---|---|
currentYear |
boolean |
- | READ ONLY True if this the current fiscal year based on the current date and time, False otherwise. |
startDate |
date |
YYYY-MM-DD |
Required The start date for this fiscal year. The distance between start date and end date may not be more than two years. |
endDate |
date |
YYYY-MM-DD |
Required The end date for this fiscal year. The distance between start date and end date may not be more than two years. |
name |
datetime |
- | Required The name of this fiscal year. Must be unique for this entity. |
status |
string |
- | Required The status of this fiscal year. Supported values: OPEN, CLOSED, REMOVED |
id |
string |
- | The budget service's key for this object. |
lastModified |
datetime |
- | READ ONLY The UTC date and time when this object was last changed. |
monthlyFiscalPeriods |
array |
fiscalPeriod |
Required The list of monthly fiscal periods in this fiscal year. Fiscal periods must complete fill the parent fiscal year with no overlaps. |
quarterlyFiscalPeriods |
array |
fiscalPeriod |
READ ONLY The list of quarterly fiscal periods in this fiscal year. If this parameter is not specified, quarterly fiscal periods are automatically generated based on the monthly fiscal periods supplied. |
yearlyFiscalPeriods |
array |
fiscalPeriod |
READ ONLY The list of yearly fiscal periods in this fiscal year. If this parameter is not specified, one period is created that fills the fiscal year. |
customFiscalPeriods |
array |
fiscalPeriod |
READ ONLY The list of custom fiscal periods in this fiscal year. Custom fiscal periods are API-only and will not display on user budget dashboards. |
openAndClosedFiscalPeriods |
array |
fiscalPeriod |
READ ONLY The list of all fiscal periods in this fiscal year, sorted by status. |
fiscalPeriods |
array |
fiscalPeriod |
READ ONLY The list of all fiscal periods in this fiscal year. |
displayName |
string |
- | READ ONLY Display name for fiscal year. For date range budget item we use this field to display. |
FiscalPeriod
| Name | Type | Format | Description |
|---|---|---|---|
currentPeriod |
boolean |
- | READ ONLY True if this the current fiscal period based on the current date and time, False otherwise. |
startDate |
date |
YYYY-MM-DD |
Required The start date for this fiscal period. Must be within the parent fiscal year. |
endDate |
date |
YYYY-MM-DD |
Required The end date for this fiscal year. Must be within the parent fiscal year. |
name |
string |
- | Required The name of this fiscal period. Must be unique for this entity. |
fiscalPeriodStatus |
string |
- | Required The status of this fiscal period. Supported values: OPEN, CLOSED, REMOVED |
periodType |
string |
- | Required The type of fiscal period. Supported values: MONTHLY, QUARTERLY, YEARLY, CUSTOM |
fiscalYearId |
string |
- | The key of the parent fiscal year for this fiscal period. |
id |
string |
- | The budget service's key for this object. |
spendDate |
date |
- | READ ONLY If the current date is after this fiscal period's start date, this field shows the current date. |
Error Response
| Name | Type | Format | Description |
|---|---|---|---|
status |
boolean |
- | False if there was an error. |
errorMessageList |
array |
errorMessage |
List of all errors detected. |
Error Message
| Name | Type | Format | Description |
|---|---|---|---|
errorType |
String |
- | WARNING or ERROR. |
errorCode |
String |
- | Text code for this error. |
errorMessage |
String |
- | Plain language error message. |
Response Headers
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7231 Allow
- RFC 7234 Cache-Control
- RFC 7230 Content-Length
- RFC 7231 Content-Type
- RFC 7231 Date
- RFC 7234 Expires
- RFC 7232 ETag
- RFC 7234 Pragma
- RFC 7231 Server
- RFC 7231 Vary
CALLOUTS
Callouts and Application Connectors
Overview
Callouts from SAP Concur allow clients to add an interaction with an outside system to their users' SAP Concur experience. The callouts require a web application, called an application connector, which SAP Concur will contact when appropriate. Application connectors can be hosted on the client's site or on a third-party hosting site.
Third-party developers can create callouts to provide SAP Concur clients access to information systems they manage. These developers partner with SAP Concur to have their application connectors reviewed. Once reviewed, applications are available for SAP Concur clients to purchase and configure.
Partner apps that want to use callout services must have their endpoint server(s) added to an SAP Concur safe list. This is done by logging a case with Support to have your host added.
The available callouts are:
- Fetch Attendee Data
- Fetch List Item
- Event Notification
- Launch External URL
Fetch Attendee and Fetch List Item send information out from SAP Concur to an application connector that interfaces with a external system. The connector runs a search on the external system. The results are then returned to SAP Concur, which presents the results to the user.
The Event Notification callout allows clients to receive notification of specific moments in the workflow of an expense report. When a report enters the desired workflow state a request is sent to the external system. The system can call into SAP Concur to get all the details of a report and perform appropriate actions.
The Launch External URL callout gives clients and developers a platform to extend the functionality of SAP Concur, providing a means to deliver custom user interactions, or access functionality found in an external system.
The client can arrange to add an Expense Entry form field that is configured to use the Launch External URL callout to a Concur Expense Entry form. Concur Expense will display this field with an attached button that launches a separate window when clicked. The window is controlled by an application connector, created by the client, a third party developer, or SAP Concur. The application connector is a web server that presents information in the window.
The application connector can access SAP Concur data through the web services, or can access data in an external system. Once the user has completed their actions in the window (such as performing a search or completing a wizard), he/she clicks a button such as "Done" that indicates he/she has concluded their work in the window. The application connector then closes the window.
The application connector can use web services to send information to SAP Concur, to update field values on the expense entry form or other form types. The application connector may send the updates before or after the user closes the window. When the user returns to SAP Concur, the page refreshes and the user sees the current values.
Process Flow

Application Connector Management
SAP Concur administrators use the Manage Application Connectors link on the Web Services page under Administration to register, test and enable application connectors.
Specifications
Security
SAP Concur will make calls to the application connector's endpoint using SSL. During configuration, SAP Concur will connect to the application connector to validate that its hostname and access credentials are valid.
SAP Concur will not be able to connect to the application connector until a certificate signed by a Certificate Authority (CA) is installed in the application connector. If you are hosting the application connector, you will need to install the signed certificate before SAP Concur can access the connector.
Authentication
Authenticating to the application connector
Expense passes credentials using HTTP Basic Auth to authenticate with the application connector. By default, these credentials are stored in the appropriate web configuration file for your platform, such as web.xml or web.config. The steps to configure Expense with the credentials are detailed below.
Managing Application Connectors
SAP Concur administrators use the Manage Application Connectors link in Web Services under Administration to register, test and enable application connectors.
User Permission
The Web Services links can be accessed by users with the following permission:
Developer Sandbox or Expense/Invoice/Travel/Travel Request Standard:
- Administer: Users with this permission can register and modify application connectors.
- Expense/Invoice/Travel/Travel Request Professional:
- Web Services Administrator: Users with this permission at companies that are Development Partners can register and modify application connectors.
- All Admin roles: Users with this permission at companies that are Development Partners can register and modify application connectors.
Accessing Application Connector Registration
The Manage Application Connectors link on the Web Services page is used to register, test and enable or disable application connectors.
To Access Application Connector Registration:
- On the home page, select Administration.
- Select Company.
- Select Web Services.
- Click Manage Application Connectors. The Application Connector Registration page appears.
Note you must be one of the roles specified in the User Permission section to complete these steps.
Registering an Application Connector
Once a development partner has configured a application connector, it must be registered with SAP Concur.
To Register an Application Connector:
- On the Application Connector Registration page, click New. (Please refer to Accessing Application Connector Registration section for how to access this page.)
In the System area, complete all of the required fields.
Field Description Name Enter the name that should appear in the list of connectors. Description Enter the description of the function of the connector, such as what back-end system it might connect to. Host Name Enter the hostname for the connector. Example: https://{servername} User Name Enter the user name required to authenticate with the host. This must be the same as the user name specified in the configuration file for the application connector. Note: the user name must be at least 10 characters and the maximum allowed length is 50 characters. Password Enter the password required to authenticate with the host. This must be the same as the password specified in the configuration file for the application connector. Note: the password must be at least 10 characters and the maximum allowed length is 50 characters. Click Test Connection. SAP Concur will attempt to connect to the test connection endpoint https://(host name)/system/v1.0/testconnection, using a GET method with the supplied credentials as HTTP Basic Authentication. If you have not configured the test connection endpoint, the test will fail.
Note: A successful Test Connection request is required to set the connector to “Verified” before it can be used for any of the callout services.
In the Services section, select an outbound message or callout that the connector will interact with.
Click Configure. The Configure Service window appears.
Enter the endpoint that the SAP Concur will connect to on the host. Example: /attendee/v1.0/find
Select the Enabled check box if the endpoint is ready for use. Usually you will do this after you have implemented and tested the endpoint in your application connector.
Click Save. The service is configured for your host.
Repeat steps 4-8 for each service to configure.
Click Save.
Modifying an Application Connector Registration
Once an application connector registration has been created, the fields can be modified. Services can be enabled or disabled from the Modify page.
To Modify an Application Connector:
- On the Application Connector Registration page, select the desired registration from the list. (Please refer to Accessing Application Connector Registration section for how to access this page.)
- Click Modify.
- Edit the system fields as necessary.
- Click Test Connection to verify your changes.
- Edit the services configurations as necessary.
- Click Save to return to the Application Connector Registration page.
Deactivating an Application Connector Registration
Application connector registrations can't be removed, but can be deactivated. Connectors are deactivated by setting all the associated services to inactive.
To Deactivate an Application Connector:
- On the Application Connector Registration page, select the desired connector. (Refer to the steps above in the Accessing Application Connector Registration section for how to access this page.)
- Click Modify.
- Select the active Service.
- Click Configure.
- Clear the Active check box.
- Click OK.
- Click Save.
Delete notification requests
Delete an event notification.
URI
https://www.concursolutions.com/api/platform/notifications/v1.0/notification/
Request
Request Parameters
notificationID: The unique identifier for the notification. Required.
Example:
https://www.concursolutions.com/api/platform/notifications/v1.0/notification/{notificationID}
URI Source: The URI is returned in the NotificationUrl element of the Response for the Get Notifications by Status function.
Headers
Authorization Header
Authorization header with OAuth token for valid SAP Concur user. Required.
The OAuth consumer must have one of the following user roles in SAP Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard.
Accept Header
- application/xml
- application/json
XML Example Request
DELETE https://www.concursolutions.com/api/platform/notifications/v1.0/notification/nOB1KNTDSV0UqiYeTsy6su$praZSogRJB6 HTTP/1.1
Authorization: OAuth {access token}
Response
Content Types
- application/xml
- application/json
Schema
The response returns an HTTP Status Code as follows:
| HTTP Code | Description |
|---|---|
| 200 Success | Notification successfully deleted. |
| 400 Bad Request | The request is malformed. Check the API document and verify the request uses the correct format. |
| 403 Forbidden | The OAuth Consumer doesn't have a required role. Check the API documentation to learn the required roles. |
Example of Successful Response
HTTPS 200 Success
Event Notification Callout
The Event Notification callout allows clients to choose to be notified through web services when certain actions take place in their SAP Concur company. If the client uses Concur Expense, the supported events are the Expense report entering the Post-Submit or Pre-Extract workflow steps. If the client uses Concur Travel Request, the supported events are the Travel Request entering the Post-Submit or Pre-Extract workflow steps. When the event happens, SAP Concur generates a notification and places it into the notification system queue. When the notification reaches the front of the queue, SAP Concur sends a request to the configured endpoint with event information.
This callout differs from the standard SAP Concur web services in the following ways:
- It uses an outbound callout where Expense calls a public facing URL provided by the application connector, which is a web server hosted by the third-party developer or client. Refer to Callouts and Application Connectors for more information.
- The application connector can also use the web services to retrieve or send SAP Concur data.
- The developer or client can configure and maintain the public web service interface (the application connector), or the connector can be maintained by SAP Concur. This guide specifies the request and response format required by SAP Concur.
- The developer or client can choose to create their own application connector using a different language, such as PHP, if preferred.
Contents
- Process Flow
- Products and Editions
- Example Use Case
- Product Restrictions
- Event Notification Process Overview
- Security
- Authentication
- Functions
Process Flow

Products and Editions
- Concur Expense Professional Edition
- Concur Request Professional Edition
- The SAP Concur Mobile App
Example Use Case
An example use of this callout is:
- A SAP Concur user submits an expense report, triggering an Event Notification.
- The notification is placed in a queue and processed in a first come, first served order.
- When the notification gets to the front of the queue, it is sent to the endpoint specified by the developer.
- The application connector returns the HTTP 200 status code, and the notification is removed from the queue.
- The developer uses the Report information to make the Get Expense Report Details request.
- The developer uses the additional information to validate some expense report information.
- The developer then uses the Post Expense Report Exceptions function to approve the report.
This is one use case for the Event Notification callout, however it can be used for a wide variety of requirements.
Product Restrictions
SAP Concur products are highly configurable, and not all clients will have access to all features.
Partner developers must determine which configurations are required for their solution prior to the review process.
Existing clients can work with Concur Advantage Technical Services to create custom applications that work with their configuration.
Event Notification Process Overview
The configuration process has the following steps:
Third-party developer, client or SAP Concur downloads, installs, configures, and customizes the application connector. The application connector may make requests to the inbound web services.
The developer or the SAP Concur clients registers the application connector.
Refer to Installation > Process for the detailed steps.
Once the configuration is complete, the callout uses the following process:
- The configured event occurs in SAP Concur.
- SAP Concur sends the request information to the specified endpoint for the application connector.
Security
SAP Concur will make calls to the application connector's endpoint using SSL. During configuration, SAP Concur will connect to the application connector to validate that its hostname and access credentials are valid.
In the code SAP Concur provides for a sample application connector, credentials are stored in a web configuration file that varies by platform, such as web.xml or web.config. However, if you are hosting the connector, you can customize where and how the credentials are stored by customizing HTTPBasicAuth.java or Authentication.cs.
Expense or Travel Request will not be able to connect to the application connector until a certificate signed by a Certificate Authority (CA) is installed in the application connector. If you are hosting the application connector, you will need to install the signed certificate before SAP Concur can access the connector.
Authentication
Authentication between SAP Concur and the application connector is performed using HTTP Basic Auth. By default, these credentials are stored in the appropriate web configuration file for your platform, such as web.xml or web.config. These credentials are entered in SAP Concur on the Register Application Connector page in Web Services under Administration.
Refer to the Callouts and Application Connectors page for more information.
Functions
Post Event Notification Request
Installation Process
The installation process includes installing the application connector, and registering it with SAP Concur.
- The third-party developer or client will create and install the application connector on their web site or a third party hosting site. The connector should be programmed to accept the requests from SAP Concur and provide the documented responses.
The client registers the application connector with SAP Concur:
- Log in to SAP Concur as an administrative user.
- Select Administration > Web Services.
- Click Manage Application Connectors.
- Click New.
- Fill out the fields:
Field Description Name Enter the name that should appear in the list of connectors. Description Enter the description of the function of the connector, such as what back-end system it might connect to. Host Name Enter the hostname for the connector. Example: https://{servername} User Name Enter the user name required to authenticate with the host. This must be the same as the user name specified in the configuration file for the application connector, using HTTP Basic Auth. Password Enter the password required to authenticate with the host. This must be the same as the password specified in the configuration file for the application connector, using HTTP Basic Auth. - In the Services section, select Send Notification.
- Click Configure. The Configure Service window appears.
- Enter the endpoint that SAP Concur will connect to on your server. Example: /concur/v1.0/notify
- Select the Enabled check box if the endpoint is ready for use. Usually you will do this after you have implemented and tested the endpoint in your application connector.
- In the Workflows section, select the workflow step for each expense report or travel request workflow that requires notifications. The two supported work steps are "External Validation - Pre-Extract" and "External Validation - Submit".
- Click OK.
- Click Test Connection. SAP Concur will attempt to access the configured endpoint with the provided user credentials.
- Click Save. The application connector is now registered with SAP Concur and enabled.
Responses and Errors
Refer to the HTTP Status Codes page for details of the common responses and errors.
Fetch Attendee Version 2 Callout
The Concur Fetch Attendee version 2.0 callout allows clients to import attendee information from their internal system to SAP Concur when a user is adding attendees to an entry. The SAP Concur service sends the attendee search fields to an application connector, created by the client, a third-party developer, or SAP Concur. The connector is hosted by the client or third-party developer, and has access to the attendee system of record. The connector uses the attendee information sent from SAP Concur to search for all matching attendee records in the client's system. Once the connector has the list of possible matches, it sends the attendee data to SAP Concur. The user sees the list of matches and can select the appropriate attendee for the entry.
This callout differs from the standard SAP Concur web services in the following ways:
- It uses an outbound message where SAP Concur calls a public facing API endpoint provided by the application connector. Refer to Callouts > Core Concepts for more information.
- The client or third-party developers can configure and maintain the public web service interface (the application connector), or the connector can be maintained by SAP Concur. This documentation specifies the request and response format required by SAP Concur.
- Clients can either choose to create their own application connector using PHP, Java, .NET etc or can use one of SAP Concur Partner's Attendee Fetch applications.
- The client SAP Concur Administrator must select the attendee types that will use this functionality during application connector registration. Once the attendee types are selected, they will be automatically configured to not allow users to create new attendees manually.
Contents
- Process Flow
- Products and Editions
- Product Restrictions
- Callout Details
- Fetch Attendee Process Overview
- Installation Process
Process Flow

Products and Editions
- Concur Expense Professional Edition
- Concur Expense Standard Edition
- Expense in the SAP Mobile App
- Concur Request Professional Edition
Product Restrictions
- SAP Concur products are highly configurable, and not all clients will have access to all features.
- Partner developers must determine which configurations are required for their solution prior to the review process.
- Existing clients can work with Concur Advantage Technical Services to create custom applications that work with their configuration.
Callout Details
Information on how to download, install, and configure the application connector is included in Callouts > Core Concepts.
Fetch Attendee Process Overview
The configuration process has the following steps:
- Client, third party developer, or SAP Concur downloads, installs, configures, and customizes the application connector.
- Optional for Professional / Premium Only: Client SAP Concur admin creates a new attendee type to use with the connector.
- Client registers the application connector, selecting the attendee types that will use the connector.
Once the configuration is complete, the callout uses the following process:
- The user selects the appropriate attendee type in the Search Attendees window.
- The user enters information into an attendee field and clicks Search.
- SAP Concur sends the attendee search field information to the application connector. This request includes all attendee fields, with any blank values formatted as an empty string.
- The application connector queries the attendee system of record and returns a list of results to SAP Concur.
NOTE: The results list is limited to 100 records. - SAP Concur displays the results in the Search Results section of the Search Attendees window.
NOTE: If the application connector does not respond or returns an error, the user is notified in a popup window within SAP Concur. SAP Concur will not resend the request unless the user manually initiates the search again. - If the user adds the attendees to the entry, the attendee information is saved in SAP Concur.
Security
SAP Concur will make calls to the application connector's endpoint using SSL. During configuration, SAP Concur will connect to the application connector to validate that its hostname and access credentials are valid.
SAP Concur will not be able to connect to the application connector until a certificate signed by a Certificate Authority (CA) is installed in the application connector. You will need to install the signed certificate before SAP Concur can access the connector.
Authentication
Authentication between SAP Concur and the application connector is performed using HTTP Basic Auth. By default, these credentials are stored in the appropriate web configuration file for your platform, such as web.xml or web.config. These credentials are entered in SAP Concur on the Register Application Connector page in Web Services under Administration.
Refer to the Installation Process for more information.
Functions
Version 3.0: Post Attendee Search Request
Installation Process
The installation process includes installing the application connector, and registering it with SAP Concur.
First, the client or third-party developer will create and install the application connector on their web site or a third party hosting site. The connector should be programmed to accept the requests from SAP Concur and provide the documented responses.
During installation, the client or developer will select and configure an externally available endpoint on the host server for SAP Concur to send the attendee search request to.
The client then registers the application connector with SAP Concur:
- Log in to SAP Concur as an administrative user.
- Select Administration > Web Services.
- Click Manage Application Connectors.
- Click New.
- Fill out the fields according to the Application Connector Fields table shown below.
- In the Services section, select Fetch Attendee.
- Click Configure. The Configure Service window appears.
- Enter the endpoint that the SAP Concur will connect to on your server. Example:
/attendee/v2.0/fetch. Note: The endpoint name should contain 'v2.0', otherwise the API defaults to v1.0 and returns a different set of fields. - Select the Active check box if the endpoint is ready for use. Usually you will do this after you have implemented and tested the endpoint in your application connector.
- Select the attendee types that will use the application connector. These attendee types will be automatically configured to not allow users to create new attendees manually.
- Click OK.
- Click Test Connection. SAP Concur will attempt to access the configured endpoint with the provided user credentials.
- Click Save. The application connector is now registered with SAP Concur and enabled.
Application Connector Fields
| Field | Description |
|---|---|
| Name | Enter the name that should appear in the list of connectors. |
| Description | Enter the description of the function of the connector, such as what back-end system it might connect to. |
| Host Name | Enter the hostname for the connector. Example: https://{servername} |
| User Name | Enter the user name required to authenticate with the host. This must be the same as the user name specified in the configuration file for the application connector, using HTTP Basic Auth. |
| Password | Enter the password required to authenticate with the host. This must be the same as the password specified in the configuration file for the application connector, using HTTP Basic Auth.1.0 |
SAP Concur Configuration
The SAP Concur administrator can select which attendee types use the connector when registering the application connector. These attendee types will be automatically configured to not allow users to create new attendees manually.
Professional/Premium Only: If desired, the administrator can create a new attendee type specifically for use with the connector.
Responses and Errors
Refer to the HTTP Status Codes for details of the common responses and errors.
Fetch List Callout
The Concur Fetch List callout allows clients to import list items from an internal system to Expense when a user is filling out list fields for an expense. The Expense service sends a request for list items to an application connector, created by the client, a third-party developer, or SAP Concur. The connector is hosted by the client or developer, and has access to the list item system of record. The connector uses the list information sent from Expense to search for all matching list items in the system of record. Once the connector has the list items, it sends the data to Expense. The user sees the list items and can select the appropriate item for the expense. When the user saves the expense, the list item is added to the list within Expense.
This callout differs from the inbound SAP Concur web services in the following ways:
- It uses an outbound message where Expense calls a public facing API endpoint provided by the application connector.
- The third-party developer or client can configure and maintain the public web service interface (the application connector), or the connector can be maintained by SAP Concur. This guide specifies the request and response format required by SAP Concur.
- The client Expense administrator must configure a list (most commonly a connected list), and SAP Concur must perform database configuration on the list before this service can be used.
Contents
- Process Flow
- Products and Editions
- Product Restrictions
- Concur Expense and Fetch List Configuration
- Fetch List Process Overview
- Security
- Authentication
- Functions
- Responses and Errors
Process Flow

Products and Editions
- Concur Expense Professional Edition
- The SAP Concur Mobile App
Product Restrictions
SAP Concur products are highly configurable, and not all clients will have access to all features.
Partner developers must determine which configurations are required for their solution prior to the review process.
Existing clients can work with Concur Advantage Technical Services to create custom applications that work with their configuration.
Concur Expense and Fetch List Configuration
Expense must have a list field configured to use an external source before this callout can be used. The client creates the list, SAP Concur configures it to use the external source, and the client creates the connected list definition if necessary. If using a connected list, Expense Admin creates a connected list definition in Forms and Fields.
To configure a Fetch List callout: 1. Follow the process to create a new Application Connector (refer to Managing Application Connectors) 2. On the Application Connector Registration page (from Manage Application Connectors), select the desired registration from the list. 3. Click Modify. 4. On the Sytem page under Services, select Fetch List. 5. Click Configure. 6. Add the details of your previously configured list(s): the List Name, List Category, Language Code, and Connected List Leve (if applicable). 7. Click Add List. (Repeat steps 6-7 until all desired lists are added.) 8. Click Active. 9. Click OK.
Note: If this Fetch List callout is made inactive and then subsequently saved on the System page, any lists that have been added to this Fetch List as a Configured List will be deleted from that Fetch List service.
Fetch List Process Overview
Once the configuration is complete, the callout uses the following process:
- The user selects the external source list field while creating an expense entry.
- Expense sends the list field information and the item codes for the previously selected levels (for connected lists) to the application connector.
- The application connector queries the list system of record and returns the set of list items to Expense.
- Expense displays the list items in a drop down list.
- The user selects the desired list item and saves the expense.
Security
SAP Concur will make calls to the application connector's endpoint using SSL. During configuration, SAP Concur will connect to the application connector to validate that its hostname and access credentials are valid.
In the code SAP Concur provides for a sample application connector, credentials are stored in a web configuration file that varies by platform, such as web.xml or web.config. However, if you are hosting the connector, you can customize where and how the credentials are stored by customizing HTTPBasicAuth.java or Authentication.cs.
Expense will not be able to connect to the application connector until a certificate signed by a Certificate Authority (CA) is installed in the application connector. You will need to install the signed certificate before SAP Concur can access the connector.
Authentication
Authentication between SAP Concur and the application connector is performed using HTTP Basic Auth. By default, these credentials are stored in the appropriate web configuration file for your platform, such as web.xml or web.config. These credentials are entered in SAP Concur on the Register Application Connector page in Web Services under Administration.
Functions
Responses and Errors
Refer to the HTTP Status Codes page for details of the common responses and errors.
Get notifications by status
Retrieves the list of event notifications that are in the supplied status.
Request
Request Parameters
status={status}
The desired status for the notification. Required. Currently supports failed.
Example:
https://www.concursolutions.com/api/platform/notifications/v1.0/notification?status={status}
Headers
Authorization Header
Authorization header with OAuth token for valid SAP Concur user. Required.
The OAuth consumer must have one of the following user roles in SAP Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard.
Accept Header
- application/xml
- application/json
Content-Type Header
application/xml
XML Example Request
GET https://www.concursolutions.com/api/platform/notifications/v1.0/notification?status=FAILED HTTP/1.1
Authorization: OAuth {access token}
Accept: application/xml
Response
Supported Content Types
- application/xml
- application/json
Schema
This request will return a NotificationsList parent element with a Notification child element for each failed notification. The Notification elements will have a Failure child element if the notification is failed.
Failure Elements
| Element | Description |
|---|---|
| Context | Message that the callout can use to provide the developer some context for the callout. |
| EventDateTime | When the event happened. Format: YYYY-MM-DD:HH:MM:SS |
| EventType | The event that triggered the callout. |
| NotificationURL | The URL the developer calls to delete a failed notification. |
| ObjectType | The type of object that triggered the notification. |
| ObjectURI | The URI for the object. The developer can use the appropriate GET function for the Object Type. |
XML Example of Successful Response
HTTP/1.1 200 OK
Content-Length: 626
Content-Type: application/xml
<?xml version="1.0" encoding="utf-8"?>
<NotificationList xmlns="http://www.concursolutions.com/api/notification/2012/06" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Notification>
<Context i:nil="true" />
<EventDateTime>2012-11-14T19:45:25</EventDateTime>
<EventType>Report Entered Expense Report Workflow Step - REPORT SUBMITTED</EventType>
<NotificationURI>https://www.concursolutions.com/api/platform/notifications/v1.0/notification/nOB1KNTDSWUcJPMV6dPDjNc$scu6EDbt9s</NotificationURI>
<ObjectType>EXPRPT</ObjectType>
<ObjectURI>https://www.concursolutions.com/api/expense/expensereport/v1.1/reportfulldetails/nxxKgLlnROzz$sHcpnRHQ$pALxamClaFfdC</ObjectURI>
</Notification>
</NotificationList>
JSON Example of Successful Response
HTTP/1.1 200 OK
Content-Length: 388
Content-Type: application/json; charset=utf-8
[
{
"Context": null,
"EventDateTime": "2012-11-14T19:45:25",
"EventType": "Report Entered Expense Report Workflow Step - REPORT SUBMITTED",
"NotificationURI": "https://www.concursolutions.com/api/platform/notifications/v1.0/notification/nOB1KNTDSWUcJPMV6dPDjNc$scu6EDbt9s",
"ObjectType": "EXPRPT",
"ObjectURI": "https://www.concursolutions.com/api/expense/expensereport/v1.1/reportfulldetails/nxxKgLlnROzz$sHcpnRHQ$pALxamClaFfdC"
}
]
Launch an external URL request v1
SAP Concur will send a request with the information in an encoded query string when the user clicks the button.
Request
URI
The Launch External URL callout launches the URI for the application connector, which can be in a custom location for each client. The standard location is:
https://{servername}/concur/form/v1.0/get
The URI is configured on the Register Application Connector page in Web Services under Administration.
The full URI for the request includes the following query string values:
https://{servername}/concur/form/v1.0/get?xcompanydomain={URL-encoded company domain}
&xuserid={URL-encoded login ID of interactive user}
&itemurl={URL-encoded url to item}
&nonce={URL-encoded timestamp}
&signature={URL-encoded signature hash}
Request Schema
| Value | Description |
|---|---|
| xcompanydomain | The company domain. |
| xuserid | The SAP Concur user ID of the logged-in user. This may be an expense delegate instead of the report owner. To get the report owner ID, use the itemurl to get the details of the expense entry, then use those details to get the associated report details, including the report owner ID. |
| itemurl | The URL-encoded URI to access the item the field appears on. An example would be the expense entry URI used by the Expense Report web service. |
| nonce | The URL-encoded GUID used to generate the signature. |
| signature | The URL-encoded signature hash. |
Authentication
To authenticate the request, the developer of the page in the application connector will need to generate an auth signature and compare it with the one passed in the query string.
When the request is received by the connector:
- Obtain the username and password for the application connector. How you do this will be specific to your implementation. Note: both the username and password must be at least 10 characters for increased security and the maximum allowed length is 50 characters.
- Parse and URL decode the following from the query string:
- xcompanydomain
- xuserid (used for subsequent web service call)
- itemurl
- nonce
- signature (used to authenticate and verify the request)
- Base64-decode the provided signature.
- Calculate your own base signature string by appending the values as such:
{xcompanydomain} + {xuserid} + {itemurl} + {connector username} + {connector password} + {nonce} - Use HMacSHA1 to generate a signature hash using the base signature string. To generate the key, concatenate the lower-case value for {connector username} and the exact {connector password}. For example, if the connector user name is JohnDoe, and the password is password, the key would be johndoepassword.
- Compare the generated signature hash with the signature hash provided in the request query string. If the signature hashes match then you know the credentials are valid and the request has not been tampered with.
NOTES:
- You can store the nonce to help prevent replay attacks if necessary.
- The order of the query parameters is not important, but the values in the base signature string must be combined in the correct order to generate the signature hash correctly.
XML Example Request
GET https://{URL to your custom connector and endpoint}
?xcompanydomain={URL-encoded company domain}
&xuserid={URL-encoded login ID of interactive user}
&itemurl={URL-encoded url to item}
&nonce={URL-encoded timestamp}
&signature={URL-encoded signature hash}
Response
Content Body
The application connector does not directly respond to the Launch External URL request. The application connector completes any updates to SAP Concur using the Inbound Web Services. The Launch External URL functionality monitors the external window, and when the window is closed, it redraws the form the user launched from to display any updated values.
Launch External URL Request v4
Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.
Launch External URL Request v4
Concur Expense will send a request with the information in an encoded query string when the user clicks the field configured to use the Launch External URL callout.
URI
The Launch External URL V4 callout launches the URI for the application connector, which can be in a custom location for each client. The standard location is:
GET https://{servername}/launchexternalurl/v4/form
The URI is configured on the Register Application Connector page in Web Services under Administration and Company.
The full URI for the request includes the following query string values:
GET https://{servername}/launchexternalurl/v4/form
logged_in_user_id={URL-encoded SAP Concur Unique Identifier of interactive user} report_owner_user_id={URL-encoded SAP Concur Unique Identifier of report owner} report_owner_employee_id={URL-encoded Employee ID (provided by the Client) of report owner} company_domain={URL-encoded company domain} item_url={URL-encoded URL to Header / Entry / Allocation} custom_field_launched_from={Custom Launch External URL form field ID.} expense_ids={URL encoded SAP Concur Entry ID (comma separated) available only for Allocation} source={HEADER/ENTRY/ALLOCATION} is_mobile={Indicates request from mobile UI} signature={URL-encoded signature hash} nonce={URL-encoded signature hash} client_auth_code={URL encoded temporary client authorization code} language_code={URL encoded language code of the logged in user}
Definitions
| Value | Description |
|---|---|
company_domain |
The client company’s domain. |
logged_in_user_id |
The SAP Concur Universal Unique Identifier (UUID) of the user that is logged into Concur Expense. For example, this may be an expense delegate instead of the report owner. |
report_owner_user_id |
The SAP Concur Universal Unique Identifier (UUID) of the report owner. |
report_owner_employee_id |
The client’s Employee ID of the report owner. |
item_url |
The URL-encoded URI to access the item where the field appears. This URL can be used to get the details of the header, Expense Entry, or Allocation. |
custom_field_launched_from |
The custom Launch External URL form field ID. |
expense_ids |
Concur Expense Entry ID, only used for requests from the Expense Allocation level. |
source |
Context of where the request was made from, either the Expense Report Header, Entry, or Allocation level. |
nonce |
The URL-encoded GUID used to generate the signature. |
signature |
The URL-encoded signature hash. |
is_mobile |
True or false indicating if the end-user is coming from the web-based instance of Concur Expense or mobile. This allows the client to display different UI for mobile devices. |
client_auth_code |
URL encoded temporary client authorization code. This will allow to call OAuth service to get a refresh and access token to access item_url. |
language_code |
Language code of the logged in user. Length between two to five characters. Default is "en". The code may be xx-XX (e.g., en-GB for British English), where xx indicates the base language and correlates to ISO 639-1, and XX specifies the local dialect, if applicable. SAP Concur supported languages are here. Information on language identifiers can be found here in the appendix (Note: a hyphen is the expected separator for this API for languages with dialects, e.g., en-GB). |
Authentication
To authenticate the request, the developer of the page in the application connector will need to generate an authentication signature and compare it with the one passed in the query string.
When the request is received by the connector:
Obtain the username and password for the application connector. How you do this will be specific to your implementation.
Parse and URL decode the following from the query string:
-
logged_in_user_id -
custom_field_launched_from -
expense_ids -
source -
company_domain -
report_owner_user_id -
report_owner_employee_id -
item_url -
nonce -
signature(used to authenticate and verify the request) -
is_mobile -
client_auth_code -
language_code
-
Base64-decode the provided signature.
Calculate your own base signature string by appending the values as such: {company_domain} + {logged_in_user_id} + {report_owner_user_id} + {report_owner_employee_id} + {item_url} + {connector username} + {connector password} + {nonce}
Use HMacSHA1 to generate a signature hash using the base signature string. To generate the key, concatenate the lower-case value for {connector username} and the exact {connector password}. For example, if the connector username is JohnDoe, and the password is password, the key would be johndoepassword.
Compare the generated signature hash with the signature hash provided in the request query string. If the signature hashes match, then you know the credentials are valid and the request has not been tampered with.
NOTES:
- You can store the nonce to help prevent replay attacks if necessary.
- The order of the query parameters is not important, but the values in the base signature string must be combined in the correct order to generate the signature hash correctly.
URL Example Request
GET https://{URL to your custom connector and endpoint}
?logged_in_user_id={URL-encoded login ID of interactive user}& report_owner_user_id={URL-encoded login ID of the report owner}& company_domain={URL-encoded company domain}& report_owner_employee_id={URL-encoded client’s Employee ID of the report owner}& item_url={URL-encoded url to item}& is_mobile={boolean}& custom_field_launched_from={URL-encoded custom field identifier}& signature={URL-encoded signature hash}& nonce={URL-encoded GUID used to generate the signature}& client_auth_code={URL-encoded auth code}& source={URL-encoded location of the report}& expense_ids={URL-encoded expense IDs if the request came from allocations}& language_code={URL-encoded language code of the logged in user}
Response
Content Body
The application connector does not directly respond to the Launch External URL request. The application connector completes any updates to Concur Expense using the inbound web services. The Launch External URL functionality monitors the external window, and when the window is closed, it redraws the form the user launched from to display any updated values.
Launch External URL v4
Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.
The Launch External URL callout gives clients and developers the ability to extend the functionality of the SAP Concur platform providing a means to deliver custom user interactions, or access functionality found in an external system. The client can add a Report Header, Expense Entry, or Allocation form field that is configured to use the Launch External URL callout. Concur Expense will display this field with an attached button that launches a separate browser window when clicked. The window is controlled by an application connector, created by a third-party developer or the client. The application connector is a web server that presents information in the window.
The application connector can access SAP Concur data through the web services, or can access data in an external system. Once the user has completed their actions in the window (such as performing a search or completing a wizard), they click a button such as “Done” that indicates the user has concluded their work in the window. Then application connector or user closes the window.
The application connector can use web services to send information to update field values on the Report Header, Expense Entry, or Allocation form types. The application connector may send the updates before or after the user closes the window. When the user returns to the SAP Concur platform, the page refreshes and they see the updated values only if the updates are made before the window is closed.
This callout differs from the standard SAP Concur web services in the following ways:
- It uses an outbound callout where Expense calls a public facing URL provided by the application connector, which is a web server hosted by the third-party developer or client. The connector domain must be on the allow list created during the configuration process.
- The application connector can also use the web services to read or update SAP Concur data.
- The developer or client can configure and maintain the public web service interface (the application connector), or the connector can be maintained by SAP Concur. This guide specifies the request and response format required.
- The client Expense administrator must configure a new form field and add the field to the desired form before this service can be used.
Prior Versions
The Launch External URL v1 will continue to work only at the Expense Entry level. Launch External URL v1 is not available on the NextGen UI for Concur Expense.
Contents
- Process Flow
- Products and Editions
- Limitations
- Callout Details
- V4 Launch External URL Process Overview
- Security
- Authentication
- Functions
- SAP Concur Expense Configuration
- Responses and Errors
- Launch External URL Form Field Configuration
- Application Connector Management
- Configure Launch External URL - V4 Service
Process Flow

Products and Editions
- Concur Expense Professional Edition, running NextGen UI for Concur Expense.
Limitations
SAP Concur products are highly configurable, and not all clients will have access to all features. Partner developers must determine which configurations are required for their solution prior to the review process. Existing clients can work with SAP Concur Integration Services to create custom applications that work with their configuration.
The Launch External URL callout is not supported for expense entry bulk editing. For situations where the data needs to be the same, we recommend configuring Copy-Down of the desired data fields.
Only the Employee role can interact with the Launch External URL configured field. Approver, Expense Processor, and Expense Processor Manager roles will not have access to trigger or interact with the Launch External URL callout configured field. When the Launch External URL field is configured, the Approver, Expense Processor, and Expense Processor Manager roles should be configured as read-only or hidden.
If Expense Assistant is used to create reports and the Launch External URL field is employed at the Report Header level, clients may consider creating a mandatory field for the Report Header to ensure users interact with the Launch External URL field.
If the Launch External URL callout is used in combination with external APIs to retrieve information from the Expense Report Header, Entry, or Allocation, we recommend configuring the Expense Form to have the Launch External URL callout field follow other fields that data will be retrieved from.
The system requires certain named fields (not custom fields) to be completed before a user can trigger the Launch External URL configured field. The system will perform an abbreviated save to make the expense record available to external APIs. These are the fields required to be completed by the end user before the Launch External URL callout can be triggered (if these fields are included and configured as site required on the form):
- At the Report Header level: Report Name, Report Date, Policy, and Start/End Date.
- At the Expense Entry level: Expense Type, Amount, Transaction Date, Payment Type, and Currency.
Any audit rules configured as Save actions will not be visible to the end user until the user returns to the SAP Concur Expense application from the pop-up window.
Callout Details
Information on how to create, install, and configure the application connector is included in Callouts and Application Connectors and below.
Launch URL Process Overview
The configuration process has the following steps:
Third-party developer, client or SAP Concur downloads, installs, configures, and customizes the application connector. The application connector may make requests to the inbound web services.
Concur Expense registers the application connector. Be ready to supply the test and production domain information.
Expense Admin creates a new form field with the Launch External URL control type and adds the field to the Report Header, Expense Entry, or Allocation form(s).
Once the configuration is complete, the callout uses the following process:
The user clicks the button next to the read-only Launch URL form field.
Concur Expense launches a new browser window and sends the Report Header, Entry, or Allocation Details URI, Company Domain, Employee ID, and Unique User ID in an encoded query string to the application connector.
The application connector parses the query string to extract the sent data.
The application connector uses an SAP Concur web service to gather information. This may be Report Header, Expense Entry, or Allocation information.
The application connector presents a web page in the new browser window for the end user. This can be a page from a commercial application, or a custom web application.
The user completes the process in the external system in the browser window.
The application connector sends any field update information to Concur Expense using the SAP Concur web services.
The user or the application connector closes the window and returns to Concur Expense.
Concur Expense reloads the page the user came from in order to display any updated field values (if the application connector sends a value before the window is closed).
Note: Concur Expense will perform a save for the area where the user came from (Entry, Allocation, Header) before the new browser window opens and upon refresh after the window is closed.
Security
Concur Expense will make calls to the application connector’s endpoint using SSL. During configuration, Concur Expense will connect to the application connector to validate that its hostname and access credentials are valid.
Concur Expense provides for a sample application connector, credentials are stored in a web configuration file that varies by platform, such as web.xml or web.config. However, if you are hosting the connector, you can customize where and how the credentials are stored by customizing HTTPBasicAuth.java or Authentication.cs.
Concur Expense will not be able to connect to the application connector until a certificate signed by a Certificate Authority (CA) is installed in the application connector. You will need to install the signed certificate before access.
Authentication
Concur Expense sends requests to the application connector using anonymous authorization (no username and password are provided) over HTTPS.
The application connector can validate the authenticity of the query by generating a signature hash from the provided variables and comparing it with the passed in values, including the signature hash that Concur Expense supplies. Two of the required variables for the signature hash are username and password, which are entered in Concur Expense on the Register Application Connector page in web services under Administration. The application connector must use the same username and password pair to generate its validation signature hash.
Details on registering your client ID can be found on the Authentication Grant page.
Functions
Details of the URI used for the Launch External URL request can be found on the V4 Launch External URL Request page.
Concur Expense Configuration
A custom field in Expense with text data type for the Expense Report Header, Entry, or Allocation must be configured as the Launch URL control type and the form field must be added to the desired form before this callout can be used. The Launch URL control type will not appear in the list until a partner application using the Launch External URL API has been registered and enabled for the company. The administrator must select either a single-line or a multi-line control type, depending on the data that will be placed in the field.
Notes:
- The Launch External URL currently only works with Professional Edition.
- The Launch External URL is available to be configured at the Expense Report Header, Entry, or Allocations-level fields.
- This Callout cannot be used with Standard Edition clients or from a Travel or Invoice field.
Responses and Errors
Refer to the HTTP Codes page for details of the common responses and errors.
Application Connector Management
SAP Concur administrators use the Manage Application Connectors link on the web services page under Administration to register, test, and enable application connectors.
Information on how to create, install, and configure the application connector is included in Callouts and Application Connectors.
Configure Launch External URL - V4 Service
On the Application Connector Registration page, select the desired registration from the list.
Click Modify.
In the Services section, select Launch External URL.
Click Configure. The Configure Service window appears.
Enter a valid URL for the endpoint that Concur Expense will connect to on the host.
- Confirm that the endpoint matches the actual endpoint of the remote service.
- "Host Name" configured above plus "endpoint" will be the actual endpoint used when Concur Expense connects to the clients' application connector.
Select the Active check box if the endpoint is ready for use. Usually you will do this after you have implemented and tested the endpoint in your application connector.
Click OK. The service is configured for your host.
Click Save, to return to the Application Connector Registration page.
Launch External URL Form Field Configuration
Create a new form field with the Launch External URL control type.
On the Administration link, select Expense, Expense Admin, and Forms and Fields.
Select Form type of the Report Header, Expense Entry, Allocation.
Click the Fields tab.
Select a custom field and click Modify Field. Enter the field information, as example shown below:
- Field Name: Cost Object
- Control Type: Launch URL (Single-line) or Launch URL (Multi-line)
- Application Connector: [Name of Application Connector Registered]
- Popup Width: 400
- Popup Height: 400
Click Save.
Go to the Forms tab and add the Launch URL field to the form.
Note: Make sure the Access Rights are set to Modify for the Employee role. Approver, Expense Processor, and Expense Processor Manager roles should be configured as read-only or hidden.
Launch External URL Callout v1
Limitations: For all new Launch External URL solutions, please use the Launch External URL v4 API.
The Launch External URL callout gives clients and developers a platform to extend the functionality of SAP Concur providing a means to deliver custom user interactions, or access functionality found in an external system. The client can arrange to add an Expense Entry form field that is configured to use the Launch External URL callout to a Concur Expense Entry form. Concur Expense will display this field with an attached button that launches a separate window when clicked. The window is controlled by an application connector, created by a third-party developer, the client, or SAP Concur. The application connector is a web server that presents information in the window.
The application connector can access SAP Concur data through the web services, or can access data in an external system. Once the user has completed their actions in the window (such as performing a search or completing a wizard), he/she clicks a button such as "Done" that indicates the user has concluded their work in the window. The application connector then closes the window.
The application connector can use web services to send information to SAP Concur to update field values on the expense entry form or other form types. The application connector may send the updates before or after the user closes the window. When the user returns to SAP Concur, the page refreshes and he/she sees the updated values.
This callout differs from the standard SAP Concur web services in the following ways:
- It uses an outbound callout where Expense calls a public facing URL provided by the application connector, which is a web server hosted by the third-party developer or client. The connector domain and IP address must be added to an SAP Concur safe list during the configuration process.
- The application connector can also use the web services to retrieve or send SAP Concur data.
- The developer or client can configure and maintain the public web service interface (the application connector), or the connector can be maintained by SAP Concur. This guide specifies the request and response format required by SAP Concur.
- The client Expense administrator must configure a new form field and add the field to the desired form before this service can be used.
Contents
- Process Flow
- Products and Editions
- Product Restrictions
- Callout Details
- Launch URL Process Overview
- Security
- Authentication
- Functions
- Concur Expense Configuration
- Responses and Errors
Process Flow

Products and Editions
- Concur Expense Professional Edition
Product Restrictions
This callout is not supported in the SAP Concur mobile application.
SAP Concur products are highly configurable, and not all clients will have access to all features.
Only the Employee role can interact with the Launch External URL configured field. Other roles such as the Approver and Processor are not able to trigger the pop-up window.
Partner developers must determine which configurations are required for their solution prior to the review process.
Existing clients can work with SAP Concur Integration Services to create custom applications that work with their configuration.
Callout Details
Information on how to download, install, and configure the application connector is included in Callouts and Application Connectors.
Launch URL Process Overview
The configuration process has the following steps:
- Third-party developer, client or SAP Concur downloads, installs, configures, and customizes the application connector. The application connector may make requests to the inbound web services.
- SAP Concur registers the application connector. SAP Concur must add the IP address and domain of the application connector to an include list. Be ready to supply the test and production domain information.
- Expense Admin creates a new form field with the Launch External URL control type and adds the field to the expense entry form(s).
Once the configuration is complete, the callout uses the following process:
- The user clicks the button next to the read-only form field.
- Expense launches a new window and sends the Expense Entry Details URI, Company Domain, and X-User ID in an encoded query string to the application connector.
- The application connector parses the query string to extract the sent data.
- The application connector uses a SAP Concur web service to gather information. This may be expense entry information, user information, or other information.
- The application connector presents a web page in the new window for the user to interact with. This can be a page from a commercial application, or a custom web application.
- The user completes the external system process. This could be a search, a wizard, or another process.
- The application connector sends any field update information to SAP Concur using the SAP Concur web services.
- The user or the application connector closes the window and returns to SAP Concur.
- SAP Concur reloads the page the user came from in order to display any updated field values.
Security
SAP Concur will make calls to the application connector's endpoint using SSL. During configuration, SAP Concur will connect to the application connector to validate that its hostname and access credentials are valid.
In the code SAP Concur provides for a sample application connector, credentials are stored in a web configuration file that varies by platform, such as web.xml or web.config. However, if you are hosting the connector, you can customize where and how the credentials are stored by customizing HTTPBasicAuth.java or Authentication.cs.
Expense will not be able to connect to the application connector until a certificate signed by a Certificate Authority (CA) is installed in the application connector. You will need to install the signed certificate before SAP Concur can access the connector.
Authentication
SAP Concur sends requests to the application connector using anonymous authorization (no username and password are provided) over HTTPS.
The application connector can validate the authenticity of the query by generating a signature hash from the provided variables and comparing it with the passed in values, including the signature hash that SAP Concur supplies. Two of the required variables for the signature hash are username and password, which are entered in SAP Concur on the Register Application Connector page in Web Services under Administration. The application connector must use the same username and password pair to generate it's validation signature hash. Note: both the username and password must be at least 10 characters for increased security and the maximum allowed length is 50 characters.
Functions
Concur Expense Configuration
An Expense text form field must be configured as the Launch URL control type and the form field must be added to the desired form before this callout can be used. The Launch URL control type will not appear in the list until a partner application using the Launch External URL API has been registered and enabled for the company. The administrator must select either a single-line or a multi-line control type, depending on the data that will be placed in the field.
Notes:
- The Launch External URL currently only works with Professional Edition.
- It is also only available to be configured at the Expense Entry-level fields.
- This Callout cannot be used with Standard Edition clients or from a Travel or Invoice field.
Responses and Errors
Refer to the HTTP Codes page for details of the common responses and errors.
Post an event notification request
Request
Supported Accept Types
- application/xml
URI
The Event Notification callout sends the notification to a URI for the application connector, which can be in a custom location for each client. The standard location is:
https://{servername}/concur/v1.0/notify
The URI is configured on the Register Application Connector page in** Web Services** under Administration.
Request Headers - Required
Authorization header with Basic authorization for endpoint. Refer to Authentication for more information.
Request Headers - Optional
None
Request Schema
The request will include a Notification parent element, with the following child elements:
| Element | Description |
|---|---|
| EventType | The event that triggered the callout. Format: Report Entered Expense Report Workflow Step - |
| ObjectType | The type of object that triggered the notification. Currently supports Expense Report and Travel Request. Format: EXPRPT, TRAVELREQ |
| ObjectURI | The URI for the object. The developer can use the appropriate GET endpoint for the Object Type. |
| EventDateTime | When the event happened. Format: YYYY-MM-DD |
| Context | Message that the callout can use to provide the developer some context for the callout. |
XML Example Request
POST /concur/v1.0/notify HTTPS/1.1
Host: www.example.com
Authorization: Basic Y29uY3VyOmNvbmN1cg==
...
<?xml version="1.0" encoding="UTF-8" ?>
<Notification>
<EventType>Report Entered Expense Report Workflow Step - SUBMIT</EventType>
<ObjectType>EXPRPT</ObjectType>
<ObjectURI>https://www.concursolutions.com/api/expense/expensereport/v1.1/reportfulldetails/3%Rek29$wsIY12Di3LS9$gjei%KL23</ObjectURI>
<EventDateTime>2012-05-01</EventDateTime>
<Context/>
</Notification>
Response
Supported Content Types
- application/txt
Content Body
The application connector responds with an HTTP 200 code when it successfully receives the notification.
Example of Successful Response
HTTPS 200 Success
Post an attendee search request
Request
URI
The Fetch Attendee version 2.0 callout sends the attendee information to a URI for the application connector, which can be in a custom location for each client. The default is:
https://{servername}/concur/attendee/v2.0/fetch
For backward compatibility, Fetch Attendee version 1.0 is used instead of version 2.0 when the URI uses v1.0 instead of v2.0. The URI is configured on the Application Connector Registration page under Web Services>Administration>Manage Applications.
The application connector responds to the Fetch Attendee request by returning all attendees that match the search criteria. The result is limited to the maximum number of records specified in the request. If more than the maximum number of records are sent, Concur Expense displays a message in the Attendee Search window asking the user to refine their search. The authorization functionality in version 2.0 is the same as version 1.0
Headers
Authorization Header
Required. Authorization header with Basic authorization for endpoint. Refer to Authentication for more information.
Request Schema
The request body contains an AttendeeSearchRequest parent element with an Attendee child element. The Attendee elements contain the values entered on the search form.
Attendee Elements
| Element | Description |
|---|---|
| AttendeeTypeCode | Code for the attendee type assigned to this attendee. Maximum length is 8 characters. |
| Company | Attendee's company. Also used for Institution Name for Healthcare Provider attendees. Maximum length is 150 characters. Required in the response. |
| Custom1 through Custom20 | Custom fields which vary for a given configuration. Maximum length is 100 characters. Required in the response. For clients who purchased the HCP Connector, Custom7, Custom8, and Custom9 are mapped to the HCP Attendee Form as follows: Custom7: License number Custom8: State of license Custom9: Healthcare specialty description |
| Custom21 through Custom25 | Custom fields which vary for a given configuration. Maximum length is 100 characters. Required in the response. For clients who purchased the HCP Connector, Custom15, Custom21, Custom22, and Custom23 are mapped to the HCP Attendee Form as follows: Custom15: Healthcare practice address Custom21: Attendee taxonomy Custom22: Attendee tax ID Custom23: Covered recipient ID |
| ExternalID | Attendee's unique identifier outside of the SAP Concur solution. Maximum length is 48 characters. |
| FirstName | Attendee's first name. Maximum length is 50 characters. |
| LastName | Attendee's last name. Maximum length is 132 characters. |
| MaximumNumberRecords | Maximum number of records that will be returned to the user for the given search criteria. |
| MiddleInitial | Attendee's middle initial. Maximum length is 1 character. |
| OwnerLoginID | SAP Concur Login ID for the report owner (not the logged in user). The developer can use the User Resource: GET endpoint to obtain user profile details that identify the user and use this information to search for attendees in the system of record for that user. |
| Suffix | Attendee's name suffix. Maximum length is 32 characters. |
| Title | Attendee's title. Maximum length is 32 characters. |
XML Example Request
POST /concur/attendee/v1.0/fetch HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml; charset=utf-8
Content-Length: {length of content body}
<AttendeeSearchRequest>
<Attendee>
<AttendeeTypeCode>BUSGUEST</AttendeeTypeCode>
<FirstName>Chris</FirstName>
<MiddleInitial />
<LastName>Miller</LastName>
<Suffix />
<Title>CFO</Title>
<Company>Len Dev</Company>
<ExternalID />
<OwnerLoginID>cm@example.com</OwnerLoginID>
<MaximumNumberRecords>500</MaximumNumberRecords>
<Custom1 />
<Custom2 />
<Custom3 />
<Custom4 />
<Custom5 />
<Custom6 />
<Custom7 />
<Custom8>North America</Custom8>
<Custom9 />
<Custom10 />
<Custom11 />
<Custom12 />
<Custom13 />
<Custom14 />
<Custom15 />
<Custom16 />
<Custom17 />
<Custom18 />
<Custom19 />
<Custom20 />
<Custom21 />
<Custom22 />
<Custom23 />
<Custom24 />
<Custom25 />
</Attendee>
</AttendeeSearchRequest>
Response
Supported Content Types
application/xml
Response Schema
The response will include an AttendeeSearchResponse parent element, with an Attendee child element for each search result.
If no attendees match the search criteria, the response returns an empty AttendeeSearchResponse.
Attendee Elements
The Attendee child element must contain all of the elements described below. The FirstName, LastName, and ExternalID elements must have values. All other elements must be returned in the response, however they can be empty if no data is available.
| Element | Description |
|---|---|
| AttendeeTypeCode | The attendee type code for the attendee type assigned to this attendee. Maximum length: 8 |
| Company | The attendee's company. Required in the response. Also used for Institution Name for Healthcare Provider attendees. Maximum length: 150 |
| Custom1 through Custom25 | Varies depending on configuration. Required in the response. Maximum length of Custom1 through Custom20: 100 characters. Maximum length of Custom21 through Custom25: 48 characters. For information about Custom fields that are used by healthcare providers, see the Custom fields for healthcare provider attendees table below. |
| ExternalID | The attendee's unique identifier outside of the SAP Concur solution. Maximum length: 32 |
| FirstName | The attendee's first name. Maximum length: 50 |
| LastName | The attendee's last name. Maximum length: 132 |
| MiddleInitial | The middle initial of the attendee. Maximum length: 1. |
| Suffix | The suffix of the attendee. Maximum length: 32. |
| Title | The attendee's title. Maximum length: 32 |
Custom Fields for Healthcare Provider Attendees
| Field | Description |
|---|---|
| Custom7 | License Number |
| Custom8 | State of License |
| Custom9 | Specialty Description |
| Custom13 | Recipient Type/Professional Designation |
| Custom14 | NPI Number |
| Custom15 | Primary Practice Address Line 1 |
| Custom16 | Primary Practice Address Line 2 |
| Custom17 | Primary Practice Address Line 3 |
| Custom18 | Primary Practice City |
| Custom19 | Primary Practice State |
| Custom20 | Primary Practice Zip Code |
| Custom21 | Taxonomy. Max 48 characters. |
| Custom22 | Tax ID. Max 48 characters. |
| Custom23 | Covered Recipient ID. Max 48 characters. |
NOTES:
- When implementing the search logic, the search criteria should use logical AND between the fields, not logical OR. For example, if in the search dialog the user specifies Doe in the last name field and Acme in the company field, the connector must return only records where the Acme company has contacts with the last name of Doe. It must not return records for contacts with the last name Doe who belong to another company such as Apex.
- If the application connector does not respond or returns an error, the user is notified in a popup window within Expense. The SAP Concur solution will not resend the request unless the user manually initiates the search again.
XML Example of Successful Response
HTTPS/1.1 200 OK
Content-Type: application/xml
Content-Length: {length of content body}
<AttendeeSearchResponse>
<Attendee>
<ExternalID>1234567890</ExternalID>
<FirstName>Chris</FirstName>
<MiddleInitial>T</MiddleInitial>
<LastName>Miller</LastName>
<Suffix/>
<Company>Len Dev</Company>
<AttendeeTypeCode>BUSGUEST</AttendeeTypeCode>
<Title>CFO</Title>
<Custom1/>
<Custom2/>
<Custom3/>
<Custom4/>
<Custom5/>
<Custom6/>
<Custom7>RD</Custom7>
<Custom8>North America</Custom8>
<Custom9>Internal Medicine</Custom9>
<Custom10/>
<Custom11/>
<Custom12/>
<Custom13/>
<Custom14/>
<Custom15>100 Main Street, Bellevue, WA 98040</Custom15>
<Custom16/>
<Custom17/>
<Custom18/>
<Custom19/>
<Custom20/>
<Custom21>Tax ID 1234</Custom21>
<Custom22/>
<Custom23>Patient ID 576</Custom23>
<Custom24/>
<Custom25/>
</Attendee>
</AttendeeSearchResponse>
The following example shows the expected response when no attendees match the search criteria.
HTTPS/1.1 200 OK
Content-Type: application/xml
Content-Length: {length of content body}
<?xml version="1.0" encoding="utf-8"?>
<AttendeeSearchResponse/>
Post a list search request
Request
Supported Accept Types
application/xml
URI
The Fetch List callout sends the attendee information to a URI for the application connector, which can be in a custom location for each client. The standard location is:
https://{servername}/concur/list/v1.2/fetch
The URI is configured on the Register Application Connector page in Web Services under Administration.
Request Headers - Required
Authorization header with Basic authorization for endpoint. Refer to Authentication for more information.
Request Headers - Optional
None
Request Schema
The request will contain a fetch-list-request parent element, containing the following child elements.
| Element | Description |
|---|---|
long-code |
The long code is a concatenated string containing the parent list item keys separated by a hyphen (-). |
short-code |
The short code is the key of the parent list item. |
query |
It is possible that the asterisk wildcard will be passed from Expense to the application connector.
|
search-by |
Indicates which list item attribute should be searched. Supported values: TEXT, CODE.NOTE: The application connector must support both attributes in order to properly handle wildcard searches. |
lang-code |
The two character code for the language of the user. |
num-to-return |
Expense will specify the number of items to return. The application connector must use this value to ensure that it does not return more results than requested. There is a system limit of 100 items. |
protected-list-key |
Internal connector information, not used by customers. |
list-name |
Internal connector information, not used by customers. |
connector-version |
Internal connector information, not used by customers. |
config-options |
Internal connector information, not used by customers. |
code-by-level |
Indicates the code at each level in the case of a multi-level list. |
XML Example Request for Single Level List
The example uses the Fetch List web service to search a single level list for all projects beginning with Alph, and is configured to connect to an application connector located at www.example.com.
POST /concur/list/v1.2/fetch HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml; charset=utf-8
Content-Length: {length of content body}
<?xml version="1.0" ?>
<fetch-list-request>
<long-code></long-code>
<short-code></short-code>
<query>Alph*</query>
<search-by>TEXT</search-by>
<lang-code>EN</lang-code>
<num-to-return>80</num-to-return>
<protected-list-key />
<list-name />
<connector-version />
<config-options />
</fetch-list-request>
XML Example Request for Multi-Level List
The example uses the Fetch List web service to search a connected list for all cities under US-W-CA (United States, Western Region, California) beginning with San, and is configured to connect to an application connector located at www.example.com.
POST /concur/list/v1.2/fetch HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml; charset=utf-8
Content-Length: {length of content body}
<?xml version="1.0" ?>
<fetch-list-request>
<long-code>US-W-CA</long-code>
<short-code>CA</short-code>
<query>San*</query>
<search-by>TEXT</search-by>
<lang-code>EN</lang-code>
<num-to-return>80</num-to-return>
<protected-list-key />
<list-name />
<connector-version />
<config-options />
<code-by-level>
<level1>US</level1>
<level2>W</level2>
<level3>CA</level3>
</code-by-level>
</fetch-list-request>
Response
Supported Content Types
application/xml
Response Schema
The application connector responds to the Fetch list web service request by returning all list items that match the search criteria.
The response will include a fetch-list-response parent element, with an item child element for each search result. If there are no search results, the fetch-list-response element is empty. The item child element contains the following child elements:
| Element | Description |
|---|---|
code |
Required The long code for the list item, consisting of the long code from the request combined with the short code from the response, separated by a hyphen (-). |
short-code |
Required The short code for the list item. |
text |
Required The list item text. |
match-value |
Required The value that matched the search term. |
XML Example of Response with Results
HTTPS/1.1 200 OK
Content-Type: application/xml
Content-Length: {length of content body}
<fetch-list-response>
<item>
<code>US-W-CA-SF</code>
<short-code>SF</short-code>
<text>San Francisco</text>
<match-value>San Francisco</match-value>
</item>
<item>
<code>US-W-CA-SD</code>
<short-code>SD</short-code>
<text>San Diego</text>
<match-value>San Diego</match-value>
</item>
<item>
<code>US-W-CA-SJ</code>
<short-code>SJ</short-code>
<text>San Jose</text>
<match-value>San Jose</match-value>
</item>
</fetch-list-response>
XML Example of Response with No Results
HTTPS/1.1 200 OK
Content-Type: application/xml
<fetch-list-response>
</fetch-list-response>
Travel Request Validation
Requests in SAP Concur can be validated in an external system by using a combination of SAP Concur callouts and web services.
This guide provides a step by step overview of how to set up and use the external validation functionality for Requests. This guide does not provide instruction on the process of programming the application connector, but provides an overview of the required functionality.
- Create an Application Connector
- Configure Event Notification and Request in SAP Concur
- Gather the Request Details
- Validate the Request Information
- Update the Request Workflow
Step 1 - Create an Application Connector
The application connector is a custom web application that is installed on your company's web server. This application needs to be accessible from outside your company's network, so that SAP Concur can send information to it, and it needs to have access to the system that you are using for validation. The application connector must be configured to accept the event notification requests from SAP Concur. In later steps, you will expand the functionality of the application connector to perform additional tasks. The required connector configuration for this step is:
- You must have a current security certificate installed on the server that hosts the application connector.
- You must expose an endpoint on your web server that SAP Concur can connect to. This endpoint can have any name or location. The default endpoint is: /concur/v1.0/notify
- You must be able to accept an HTTP POST from SAP Concur with the event notification data. Refer to the Event Notification information for details of the information format. You just need to store the data that SAP Concur sends for this step.
- You must have a username and password configured for the host web server, which SAP Concur will use when sending the HTTP POST request. This username and password is sent using HTTP Basic Auth.
Once you have the basic application connector functionality set up, you're ready to move to the next step.
Step 2 - Configure Event Notification and Request in SAP Concur
In this step, you will enable the Event Notification functionality in your SAP Concur company in order to receive information about submitted Requests. Then, you will enable the Request API in order to request Request details from SAP Concur.
Before you begin:
- You must have a user login with administrative privileges in SAP Concur.
- You must know which Request workflows require the Event Notification functionality.
Procedure: Create the Event Notification Application Connector
- Log in to SAP Concur as an administrative user.
- Select Administration > Web Services.
- Click Manage Application Connectors.
- Click New.
- Fill out the fields:
|Field|Description|
|-----|------|
| Name | Enter the name that should appear in the list of connectors. |
| Description | Enter the description of the function of the connector, such as what back-end system it connects to. |
| Host Name | Enter the hostname for the connector. Example: https://{servername} |
| User Name | Enter the user name required to authenticate with the host. This must be the same as the user name specified in the configuration file for the application connector, using HTTP Basic Auth. |
| Password | Enter the password required to authenticate with the host. This must be the same as the password specified in the configuration file for the application connector, using HTTP Basic Auth. |
6. In the Services section, select External Report Validation.
7. Click Configure. The Configure Service window appears.
8. Enter the endpoint that the SAP Concur will connect to on your server. Example: /concur/v1.0/notify
9. Select the Enabled check box.
10. In the Workflows section, select the Submit check box for each Request workflow that requires notifications.
11. Click OK.
12. Click Test Connection. SAP Concur will attempt to access the configured endpoint with the provided user credentials.
13. Click Save. The application connector is now registered with SAP Concur and enabled.
Procedure: Create the Request Partner Application
- On the Web Services page, click Register Partner Application. The Application Registration page appears.
- Click New. The New Partner Application page appears.
- Complete all of the required fields:
|Field |Description | |--------|-------| | Name | Enter the name that should appear in the list of applications. | | Description | Enter the description of the function of the application. | | Visibility | This field is only editable by SAP Concur Internal users. | | Active | Select Active. | | APIs Used | Select the Request API. |
- The Application Authorization section displays your company domain and automatically creates a Key and Secret to use with this application.
NOTE: The key and secret allow access to any company that enables this application. You MUST keep this information secret (as specified in the SAP Concur Legal Agreement) to maintain security. - Record the key and secret to use later.
- Click OK. The application will automatically be enabled for your company.
You should now begin receiving notifications from SAP Concur when your users submit Requests. In the next step, you'll use the notification data that SAP Concur sends to get the Request information.
Step 3 - Gather the Request Details
In this step, you will expand the application connector functionality to use the data sent by SAP Concur in the event notification to get details about the Request. You'll use the Request details to validate the Request in a later step. The application connector must be updated to perform the following steps, using the SAP Concur web services:
Get OAuth Access Token
All requests to SAP Concur web services must be authenticated using OAuth 2.0.
After receiving an event notification, the application connector should send an HTTP GET request to the Get Access Token using Native Flow function. This function requires the login credentials of an administrative SAP Concur user and the Consumer Key that was generated when you created the partner application in the previous step. Refer to the Get Access Token using Native Flow documentation for the format of the request. SAP Concur will respond to the request with the access token required for the next web service request.
Get Request Details
After you receive the OAuth access token, you are ready to request the Request data. The event notification information that SAP Concur sends includes an element named ObjectURI. The connector can send a GET request to the URI specified in this element, supplying the OAuth access token in the request header in the following format:
GET api/travelrequest/v1.0/requests/nxxKgLlnROz3zHJBCRksaas23dsfs HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
...
Step 4 - Validate the Request Information
In this step, the connector will perform the required validation on the Request information. This step will vary by client. The application connector must be able to access the system(s) used in the validation.
The Request data is validated by the application connector. The validation can produce one of the following results:
- The Request passed validation and can be approved.
- The Request did not pass validation and must be returned to the employee with an informational message explaining the problem.
In the next step, the application connector will update the Request with the validation results.
Step 5 - Update the Request Workflow
Once the Request has been validated, the application connector is ready to update its workflow. If the Request passed validation, it should be approved, and will then travel forward in its workflow. If the Request did not pass validation, it should be sent back to the employee, which moves it to the beginning of the workflow.
The full Request details include an element named WorkflowStepURL. The application connector posts the workflow action (Approve or Send Back to Employee) to this url, using the same OAuth access token in the header.
SAP Concur responds with a success or failure status, and provides additional information for failures.
The application connector has now completed the process of validating a Request, from the initial notification that a Request was submitted, to the request updating the Request workflow in SAP Concur with the validation results.
Launch External URL Request v4
Launch External URL Request v4
Concur Expense will send a request with the information in an encoded query string when the user clicks the field configured to use the Launch External URL callout.
URI
The Launch External URL V4 callout launches the URI for the application connector, which can be in a custom location for each client. The standard location is:
GET https://{servername}/launchexternalurl/v4/form
The URI is configured on the Register Application Connector page in Web Services under Administration and Company.
The full URI for the request includes the following query string values:
GET https://{servername}/launchexternalurl/v4/form
logged_in_user_id={URL-encoded SAP Concur Unique Identifier of interactive user} report_owner_user_id={URL-encoded SAP Concur Unique Identifier of report owner} report_owner_employee_id={URL-encoded Employee ID (provided by the Client) of report owner} company_domain={URL-encoded company domain} item_url={URL-encoded URL to Header / Entry / Allocation} custom_field_launched_from={Custom Launch External URL form field ID.} expense_ids={URL encoded SAP Concur Entry ID (comma separated) available only for Allocation} source={HEADER/ENTRY/ALLOCATION} is_mobile={Indicates request from mobile UI} signature={URL-encoded signature hash} nonce={URL-encoded signature hash} client_auth_code={URL encoded temporary client authorization code} language_code={URL encoded language code of the logged in user}
Definitions
| Value | Description |
|---|---|
company_domain |
The client company’s domain. |
logged_in_user_id |
The SAP Concur Universal Unique Identifier (UUID) of the user that is logged into Concur Expense. For example, this may be an expense delegate instead of the report owner. |
report_owner_user_id |
The SAP Concur Universal Unique Identifier (UUID) of the report owner. |
report_owner_employee_id |
The client’s Employee ID of the report owner. |
item_url |
The URL-encoded URI to access the item where the field appears. This URL can be used to get the details of the header, Expense Entry, or Allocation. |
custom_field_launched_from |
The custom Launch External URL form field ID. |
expense_ids |
Concur Expense Entry ID, only used for requests from the Expense Allocation level. |
source |
Context of where the request was made from, either the Expense Report Header, Entry, or Allocation level. |
nonce |
The URL-encoded GUID used to generate the signature. |
signature |
The URL-encoded signature hash. |
is_mobile |
True or false indicating if the end-user is coming from the web-based instance of Concur Expense or mobile. This allows the client to display different UI for mobile devices. |
client_auth_code |
URL encoded temporary client authorization code. This will allow to call OAuth service to get a refresh and access token to access item_url. |
language_code |
Language code from the logged in user's profile (or overriden language from the manually selected language at login for the session). Length between two to five characters. Default is "en". The code may be xx-XX (e.g., en-GB for British English), where xx indicates the base language and correlates to ISO 639-1, and XX specifies the local dialect, if applicable. SAP Concur supported languages are here. Information on language identifiers can be found here in the appendix (Note: a hyphen is the expected separator for this API for languages with dialects, e.g., en-GB). |
Authentication
To authenticate the request, the developer of the page in the application connector will need to generate an authentication signature and compare it with the one passed in the query string.
When the request is received by the connector:
Obtain the username and password for the application connector. How you do this will be specific to your implementation. Note: both the username and password must be at least 10 characters for increased security and the maximum allowed length is 50 characters.
Parse and URL decode the following from the query string:
-
logged_in_user_id -
custom_field_launched_from -
expense_ids -
source -
company_domain -
report_owner_user_id -
report_owner_employee_id -
item_url -
nonce -
signature(used to authenticate and verify the request) -
is_mobile -
client_auth_code -
language_code
-
Base64-decode the provided signature.
Calculate your own base signature string by appending the values as such: {company_domain} + {logged_in_user_id} + {report_owner_user_id} + {report_owner_employee_id} + {item_url} + {connector username} + {connector password} + {nonce}
Use HMacSHA256 to generate its signature (message authentication code) hash using the base signature string. To generate the key, concatenate the lower-case value for {connector username} and the exact {connector password}. For example, if the connector username is "JohnDoe", and the password is "Password", the key would be "johndoePassword".
Compare the generated signature hash with the signature hash provided in the request query string. If the signature hashes match, then you know the credentials are valid and the request has not been tampered with.
NOTES:
- You can store the nonce to help prevent replay attacks if necessary.
- The order of the query parameters is not important, but the values in the base signature string must be combined in the correct order to generate the signature hash correctly.
URL Example Request
GET https://{URL to your custom connector and endpoint}
?logged_in_user_id={URL-encoded login ID of interactive user}& report_owner_user_id={URL-encoded login ID of the report owner}& company_domain={URL-encoded company domain}& report_owner_employee_id={URL-encoded client’s Employee ID of the report owner}& item_url={URL-encoded url to item}& is_mobile={boolean}& custom_field_launched_from={URL-encoded custom field identifier}& signature={URL-encoded signature hash}& nonce={URL-encoded GUID used to generate the signature}& client_auth_code={URL-encoded auth code}& source={URL-encoded location of the report}& expense_ids={URL-encoded expense IDs if the request came from allocations}& language_code={URL-encoded language code of the logged in user}
Response
Content Body
The application connector does not directly respond to the Launch External URL request. The application connector completes any updates to Concur Expense using the inbound web services. The Launch External URL functionality monitors the external window, and when the window is closed, it redraws the form the user launched from to display any updated values.
Launch External URL v4
The Launch External URL callout gives clients and third-party developers the ability to extend the functionality of the SAP Concur platform providing a means to deliver custom user interactions, or access functionality found in an external system. The client can add a Report Header, Expense Entry, or Allocation form field that is configured to use the Launch External URL callout. Concur Expense will display this field with an attached button that launches a separate browser window when clicked. The window is controlled by an application connector, created by a third-party developer or the client. The application connector is a web server that presents information in the window.
The application connector can access SAP Concur data through the web services, or can access data in an external system. Once the user has completed their actions in the window (such as performing a search or completing a wizard), they click a button such as “Done” that indicates the user has concluded their work in the window. The application connector or user closes the window.
The application connector can use web services to send information to update field values on the Report Header, Expense Entry, or Allocation form types. The application connector may send the updates before or after the user closes the window. When the user returns to the SAP Concur platform, the page refreshes and they see the updated values only if the updates are made before the window is closed.
This callout differs from the standard SAP Concur web services in the following ways:
- It uses an outbound callout where Expense calls a public facing URL provided by the application connector, which is a web server hosted by the third-party developer or client. The connector domain must be on the allow list created during the configuration process.
- The application connector can also use the web services to read or update SAP Concur data.
- The developer or client can configure and maintain the application connector, or the connector can be maintained by SAP Concur. This guide specifies the request and response format required.
- The client Expense administrator must configure a new form field and add the field to the desired form before this service can be used.
Contents
- Process Flow
- Products and Editions
- Limitations
- Launch External URL Process Overview
- Security
- Authorization
- Functions
- Concur Expense Configuration
- Responses and Errors
- Launch External URL Form Field Configuration
- Application Connector Management
- Configure Launch External URL - V4 Service
Prior Versions
The Launch External URL v1 will continue to work only at the Expense Entry level.
Process Flow

Products and Editions
- Concur Expense Professional Edition, running NextGen UI for Concur Expense
- The SAP Concur mobile app
Limitations
SAP Concur products are highly configurable, and not all clients will have access to all features. Partner developers must determine which configurations are required for their solution prior to the review process. Existing clients can work with SAP Concur Integration Services to create custom applications that work with their configuration.
The Launch External URL callout is not supported for expense entry bulk editing. For situations where the data needs to be the same, we recommend configuring Copy-Down of the desired data fields.
Only the Employee role can interact with the Launch External URL configured field. Approver, Expense Processor, and Expense Processor Manager roles will not have access to open or interact with the Launch External URL callout configured field. When the Launch External URL field is configured, the Approver, Expense Processor, and Expense Processor Manager roles should be configured as read-only or hidden.
If Expense Assistant is used to create reports and the Launch External URL field is employed at the Report Header level, clients may consider creating a mandatory field for the Report Header to ensure users interact with the Launch External URL field.
If the Launch External URL callout is used as part of a process with other Expense APIs to retrieve information from the Expense Report Header, Entry, or Allocation, we recommend configuring the Expense Form to have the Launch External URL callout field follow other fields that data will be retrieved from (i.e., place the Launch External URL callout field sequentially after the other fields).
The system requires certain named fields (not custom fields) to be completed before a user can open the Launch External URL configured field. The system will perform an abbreviated save to make the expense record available to external APIs. These are the fields required to be completed by the end user before the Launch External URL callout can be opened (if these fields are included and configured as site required on the form):
- At the Report Header level: Report Name, Report Date, Policy, and Start/End Date.
- At the Expense Entry level: Expense Type, Amount, Transaction Date, Payment Type, and Currency.
Any audit rules configured as Save actions will not be visible to the end user until the user returns to the Concur Expense application from the pop-up window.
The Android app is currently in pre-release status and is only available to approved early access participants. To become an early access participant, contact your SAP Concur Representative.
Launch External URL v4 is not currently supported in the China Datacenter.
Launch URL Process Overview
The configuration process has the following steps:
Third-party developer, client or SAP Concur downloads, installs, configures, and customizes the application connector. The application connector may make requests to the inbound web services.
Concur Expense registers the application connector. Be ready to supply the test and production domain information.
Expense Admin creates a new form field with the Launch External URL control type and adds the field to the Report Header, Expense Entry, or Allocation form(s).
Once the configuration is complete, the callout uses the following process:
The user clicks the button next to the read-only Launch URL form field.
Concur Expense launches a new browser window and sends the Report Header, Entry, or Allocation Details URI, Company Domain, Employee ID, and Unique User ID in an encoded query string to the application connector.
The application connector parses the query string to extract the sent data.
The application connector uses an SAP Concur web service to gather information. This may be Report Header, Expense Entry, or Allocation information.
The application connector presents a web page in the new browser window for the end user. This can be a page from a commercial application, or a custom web application.
The user completes the process in the external system in the browser window.
The application connector sends any field update information to Concur Expense using the SAP Concur web services.
The user or the application connector closes the window and returns to Concur Expense.
Concur Expense reloads the page the user came from in order to display any updated field values (if the application connector sends a value before the window is closed).
Note: Concur Expense will perform a save for the area where the user came from (Entry, Allocation, Header) before the new browser window opens and upon refresh after the window is closed.
Security
Concur Expense will make calls to the application connector’s endpoint using SSL. During configuration, Concur Expense will connect to the application connector to validate that its hostname and access credentials are valid.
Concur Expense provides for a sample application connector, credentials are stored in a web configuration file that varies by platform, such as web.xml or web.config. However, if you are hosting the connector, you can customize where and how the credentials are stored by customizing HTTPBasicAuth.java or Authentication.cs.
Concur Expense will not be able to connect to the application connector until a certificate signed by a Certificate Authority (CA) is installed in the application connector. You will need to install the signed certificate before access.
Authorization
Launch External URL V4 uses the Authentication Grant process. When Launch External URL V4 calls are made, and the end-user is already logged into Concur, the customer or third party application will receive a temporary token in the query parameter, "client_auth_code". Since the Launch External URL callout completes the first leg of this 3-legged Oauth2 grant, your application must then exchange the temporary token for a refresh token and access token. For this, please refer to the Authentication Grant page for the POST /oauth2/v0/token details.
Note: users must be logged into their Concur account for this process to work correctly.
Information on the Launch External URL setup is provided in the Configure Launch External URL - V4 Service section below.
Functions
Details of the URI used for the Launch External URL request can be found on the V4 Launch External URL Request page.
Concur Expense Configuration
A custom field in Expense with text data type for the Expense Report Header, Entry, or Allocation must be configured as the Launch URL control type and the form field must be added to the desired form before this callout can be used. The Launch URL control type will not appear in the list until a partner application using the Launch External URL API has been registered and enabled for the company. The administrator must select either a single-line or a multi-line control type, depending on the data that will be placed in the field.
Note: * The Launch External URL currently only works with Professional Edition. * The Launch External URL is available to be configured at the Expense Report Header, Entry, or Allocations-level fields. * This Callout cannot be used with Standard Edition clients or from a Travel or Invoice field.
Responses and Errors
Refer to the HTTP Codes page for details of the common responses and errors.
Application Connector Management
SAP Concur administrators use the Manage Application Connectors link on the web services page under Administration to register, test, and enable application connectors.
Information on how to create, install, and configure the application connector is included in Callouts and Application Connectors.
Note: The application connector must use the same username and password pair to generate its validation signature hash. Both the username and password must be at least 10 characters for increased security and the maximum allowed length is 50 characters.
Configure Launch External URL - V4 Service
Your client ID must first be registered. Details on registering your client ID can be found on the Authentication Grant page. The client ID used for the callout must have the redirect URL registered and the following grants assigned.
Required Grants: refresh_token, password, client_credentials, and authorization_code
No scopes are required to use the Launch External URL callout. However, if the Launch External URL callout is used as part of a process with other Concur APIs, scopes for those other APIs will be needed.
The following steps explain how to register an application connector.
On the Application Connector Registration page, select the desired registration from the list.
Click Modify.
In the Services section, select Launch External URL.
Click Configure. The Configure Service window appears.
Enter a valid URL for the endpoint that Concur Expense will connect to on the host.
- Confirm that the endpoint matches the actual endpoint of the remote service.
- "Host Name" configured above plus "endpoint" will be the actual endpoint used when Concur Expense connects to the clients' application connector.
Select the Active check box if the endpoint is ready for use. Usually you will do this after you have implemented and tested the endpoint in your application connector.
Ensure the Service Version is set to V4 (only required if moving from V1 to V4).
Enter the Client ID (used to identify your application).
Enter the Redirect URL (base URL from which client will call to get User JWT).
Click OK. The service is configured for your host.
Click Save, to return to the Application Connector Registration page.
Launch External URL Form Field Configuration
Create a new form field with the Launch External URL control type.
Click Administration > Expense > Forms and Fields (left menu).
Select the Form Type of Expense Report Header, Expense Entry, or Expense Allocation.
Click the Fields tab.
Select a custom field and click Modify Field. Enter the field information, as example shown below:
- Field Name: Cost Object
- Control Type: Launch URL (Single-line) or Launch URL (Multi-line)
- Application Connector: [Name of Application Connector Registered]
- Popup Width: 400
- Popup Height: 400
Click Save.
Go to the Forms tab and add the newly created field to the form.
Important Note: Make sure the Access Rights are set to Modify for the Employee role. Approver, Expense Processor, and Expense Processor Manager roles should be configured as read-only or hidden.
CASH-ADVANCE
Cash Advance v4
Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.
The Cash Advance API can be used to create, view, and issue a cash advance.
Limitations: This API is only available to clients who have been granted access by SAP Concur. Access to this documentation does not provide access to the API. This API is not available for partner or third party use. This API is not available in Implementation environments. Cash Advance APIs supports single Cash Advance Creation, Retrieval and Issuance. Create Cash Advance API currently does not support receipt upload.
- Process Flow
- Products and Editions
- Scope Usage
- Dependencies
- Access Token Usage
- Create a Cash Advance
- Retrieve a Cash Advance
- Issue a Cash Advance
- Schema
Process Flow

Products and Editions
- Concur Expense Professional Edition
- Concur Expense Standard Edition
Scope Usage
| Name | Description | Endpoint |
|---|---|---|
cashadvance.write |
Create, Retrieve and Issue a cash advance. | GET, POST |
Dependencies
The client may use the following SAP Concur APIs to get information:
* Identity v4, to retrieve the userId.
Access Token Usage
This API supports user and company level access tokens only.
Create a Cash Advance
Creates a cash advance.
Scopes
cashadvance.write - Refer to Scope Usage for full details.
Request
URI
Template
https://{datacenterURI}/cashadvance/v4/cashadvances
Parameters
None.
Headers
- RFC 7231 Content-Type
- RFC 7235 Authorization - Bearer Token that identifies the caller. This is the User or Company access token.
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace.
Payload
Response
Status Codes
- 201 Created
- 400 Bad Request
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found
- 408 Request Timeout
- 500 Internal Server Error
- 503 Service Unavailable
Payload
Example
Request
https://us.api.concursolutions.com/cashadvance/v4/cashadvances \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access_token}' \
-H 'Content-Type: application/json' \
-H 'concur-correlationid: create-cash-advance-test' \
-d '{
"accountCode": "employee account code",
"amountRequested": {
"currency": "USD",
"amount": 100
},
"comment": "Cash Advance of local trips",
"name": "Cash Advance for Chicago",
"purpose": "Trip to home office",
"userId": "9FED321D-3484-49F3-A514-84CB2590DFC4"
}
Response
201 Created
{
"cashAdvanceId": "C0550587A7D7DF4AB41CA8EF72F6F3D1"
}
Retrieve a Cash Advance
Retrieve a cash advance.
Scopes
cashadvance.write - Refer to Scope Usage for full details.
Request
URI
Template
https://{datacenterURI}/cashadvance/v4/cashadvances/{cashAdvanceId}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
cashAdvanceId |
string |
- | Required Cash advance ID. |
Headers
- RFC 7235 Authorization - Bearer Token that identifies the caller. This is the User or Company access token.
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
Response
Status Codes
- 200 OK
- 400 Bad Request
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found
- 408 Request Timeout
- 500 Internal Server Error
- 503 Service Unavailable
Payload
Example
Request
https://us.api.concursolutions.com/cashadvance/v4/cashadvances/C0550587A7D7DF4AB41CA8EF72F6F3D1 \
-H 'Authorization: Bearer {access_token}' \
-H 'concur-correlationid: create-cash-advance-test' \
-d '{
}
Response
200 OK
{
"paymentType": {
"description": "Payment in cash",
"paymentCode": "CASH"
},
"exchangeRate": {
"operation": "MULTIPLY",
"value": "1.00000000000000"
},
"amountRequested": {
"amount": "100.000000",
"value": "100.000000",
"currency": "USD"
},
"availableBalance": {
"amount": "0.0",
"currency": "USD"
},
"approvalStatus": {
"name": "Not Submitted",
"code": "C_NOTF"
},
"cashAdvanceId": "83C46E6ADBD7D647B1AC34D1C0574E87",
"requestDate": "2020-10-29 18:28:11.0",
"name": "Cash Advance for Chicago",
"purpose": "Trip to home office",
"issuedDate": null,
"accountCode": "employee account cod",
"comment": "Cash Advance of local trips",
"lastModifiedDate": "2020-10-29 18:28:11.0",
"hasReceipts": false,
"reimbursementCurrency": "USD"
}
Issue a Cash Advance
Issues a cash advance.
Scopes
cashadvance.write - Refer to Scope Usage for full details.
Request
URI
Template
https://{datacenterURI}/cashadvance/v4/cashadvances/{cashAdvanceId}/issue
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
cashAdvanceId |
string |
- | Required Cash advance ID. |
Headers
- RFC 7231 Content-Type
- RFC 7235 Authorization - Bearer Token that identifies the caller. This is the User or Company access token.
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
Payload
Response
Status Codes
- 200 OK
- 400 Bad Request
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found
- 408 Request Timeout
- 500 Internal Server Error
- 503 Service Unavailable
Payload
Example
Request
https://us.api.concursolutions.com/cashadvance/v4/cashadvances/C0550587A7D7DF4AB41CA8EF72F6F3D1/issue \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access_token}' \
-H 'Content-Type: application/json' \
-H 'concur-correlationid: create-cash-adavance-test' \
-d '{
"accountCode": "employee account code",
"comment": "Issuing Cash Advance of employee local trips",
"exchangeRate": 1.00000
}
Response
200 OK
{
"issuedDate": "2020-10-29",
"status": {
"code": "C_ISSU",
"name": "Issued"
}
}
Schema
Create Cash Advance Request
| Name | Type | Format | Description |
|---|---|---|---|
accountCode |
string |
- | The account code, if not provided, will be read from the employee profile configuration data. Maximum characters: 48 |
amountRequested |
- | amount |
Required The amount of the cash advance. |
comment |
string |
- | Comment while creating a cash advance. Maximum characters: 2000 |
name |
string |
- | Required Cash advance name. Maximum characters: 40 |
purpose |
string |
- | Purpose of raising a cash advance. Maximum characters: 2000 |
userID |
string |
- | Required The unique identifier of the SAP Concur user. Use Identity v4 to retrieve the userID. Maximum characters: 16 |
Amount
| Name | Type | Format | Description |
|---|---|---|---|
currency |
string |
- | Required The 3-letter ISO 4217 currency code. Maximum characters: 3 |
amount |
number |
- | Required The amount value. Maximum characters: 23 |
Create Cash Advance Response
| Name | Type | Format | Description |
|---|---|---|---|
cashAdvanceId |
string |
- | Unique cash advance identifier. |
Get Cash Advance Response
| Name | Type | Format | Description |
|---|---|---|---|
paymentType |
- | payment |
Details on type of the payment used. |
exchangeRate |
- | exchangeRate |
Details on the exchange rate. Maximum characters: 23 |
amountRequested |
- | amountRequested |
Details on the amount requested. |
availableBalance |
- | availableBalance |
Details on the available balance. |
approvalStatus |
- | approvalStatus |
Details on the approval status. |
cashAdvanceId |
string |
- | Unique cash advance identifier. |
requestDate |
string |
YYYY-MM-DD |
The date the cash advance was requested. |
name |
string |
- | Cash advance name. Maximum characters: 40 |
purpose |
string |
- | Purpose of raising a cash advance. Maximum characters: 2000 |
issuedDate |
string |
YYYY-MM-DD |
The date the cash advance was issued. |
accountCode |
string |
- | Account code linked to the employee. |
comment |
string |
- | Comment while creating a cash advance. Maximum characters: 2000 |
lastModifiedDate |
string |
YYYY-MM-DD |
The date the cash advance was last modified. |
hasReceipts |
string |
- | If the cash advance has receipts. |
reimbursementCurrency |
string |
- | The 3-letter ISO 4217 currency code. Maximum characters: 3 |
payment
| Name | Type | Format | Description |
|---|---|---|---|
description |
string |
- | The payment method for the cash advance. |
paymentCode |
string |
- | The ID of the payment type for the cash advance. |
exchangeRate
| Name | Type | Format | Description |
|---|---|---|---|
operation |
string |
- | Exchange rate operation. Supported values: MULTIPLY |
value |
number |
- | Exchange rate value. |
amountRequested
| Name | Type | Format | Description |
|---|---|---|---|
amount |
number |
- | Requested cash advance amount. Maximum characters: 23 |
value |
number |
- | Deprecated (Use amount). |
currency |
number |
- | The 3-letter ISO 4217 currency code. Maximum characters: 3 |
availableBalance
| Name | Type | Format | Description |
|---|---|---|---|
amount |
number |
- | Unsubmitted balance. Maximum characters: 23 |
currency |
number |
- | The 3-letter ISO 4217 currency code. Maximum characters: 3 |
approvalStatus
| Name | Type | Format | Description |
|---|---|---|---|
name |
string |
- | Cash advance status name. Maximum characters: 40 |
code |
string |
- | Cash advance status key. |
Issue Cash Advance Request
| Name | Type | Format | Description |
|---|---|---|---|
accountCode |
string |
- | Account code linked to the employee. |
comment |
string |
- | Comment while issuing a cash advance. Maximum characters: 2000 |
exchangeRate |
number |
- | The exchange rate that applies to the expected expense.If no exchange rate is provided system exchange rate will be considered. Maximum characters: 23 |
Issue Cash Advance Response
| Name | Type | Format | Description |
|---|---|---|---|
status |
- | status |
Details on type of payment used. |
issuedDate |
string |
YYYY-MM-DD |
The date the cash advance was issued. |
status
| Name | Type | Format | Description |
|---|---|---|---|
code |
string |
- | Cash advance status key. |
name |
string |
- | Cash advance status name. Maximum characters: 40 |
Error
| Name | Type | Format | Description |
|---|---|---|---|
errorCode |
string |
- | The unique identifier of the error. |
errorMessage |
string |
- | Message associated with the error. |
COMMON
Connection Requests v3.2
The Connection Requests resource is used to integrate TripLink partner applications with Concur. It can be used to create, update, and manage connections between a user's Concur account and a select travel loyalty program. With Connection Requests a TripLink partner application can retrieve new connection requests in order to match users who want to connect to the supplier with the user's account in the supplier system. After the request is retrieved, the supplier is expected to provide a status if the connection was successful or failed. When retrieving new connections, the results can be filtered by status, page offset, and a limit for the number of records to return.
In version 3.2, connection requests can also associate users to either loyalty programs, Concur verified e-mail addresses, or both of these factors. Concur verified emails are email addresses where a user has taken additional steps to confirm an email belongs to them by entering a verification code within the Concur UI after receiving this in their email. Verified emails have uniqueness across all user accounts in the Concur system.
The use of loyalty numbers and/or verified emails to identify users is based on the business agreement between Concur and the TripLink supplier and will be discussed during the TripLink integration kick-off process. Email or loyalty number will not be returned in the connection request if the supplier is not using these factors in their process to match a user in their system to a Concur user.
Our recommendation for suppliers is to match users requesting to connect utilizing last name and loyalty number only. Or in the case of suppliers without loyalty numbers to use verified email and the last name of the user only. The first name and middle name fields have proved to generate a high degree of failures when utilized due to issues like nicknames within the supplier systems.
- Retrieve all connection requests that match the TripLink supplier ID
- Retrieve a connection request by ID
- Create a connection request on behalf of a specific user
- Update a connection request
- Schema 3.2
- Schema 3.0 (deprecated)
Connection Requests v3.0 is deprecated.
Connection Requests v3.1 is deprecated.
Retrieve all connection requests that match the TripLink supplier ID
GET /api/v3.2/common/connectionrequests/
GET /api/v3.0/common/connectionrequests/ (deprecated)
GET /api/v3.1/common/connectionrequests/ (deprecated)
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
offset |
query |
string |
The starting point of the next set of results, after the limit specified in the limit field has been reached. The default is the beginning of the page. |
limit |
query |
Int32 |
The number of records to return. The default is 5 and the maximum is 10. |
status |
query |
string |
The status code representing the state of the connection request. The possible values are Pending, Processing, Connected, Failed, and Retry. |
Retrieve a connection request by ID
GET /api/v3.2/common/connectionrequests/{id}
GET /api/v3.0/common/connectionrequests/{id} (deprecated) GET /api/v3.1/common/connectionrequests/{id} (deprecated)
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
path |
string |
Required The connection request ID. |
Create a connection request on behalf of a specific user
POST /api/v3.2/common/connectionrequests/
POST /api/v3.0/common/connectionrequests/ (deprecated) POST /api/v3.1/common/connectionrequests/ (deprecated)
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
user |
query |
string |
Required The login ID of the user for whom to create the connection request. The user must have the Web Services Admin role to use this parameter. |
Update a connection request
PUT /api/v3.2/common/connectionrequests/{id}
PUT /api/v3.0/common/connectionrequests/{id} (deprecated) PUT /api/v3.1/common/connectionrequests/{id} (deprecated)
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
path |
string |
Required The connection request ID. |
content |
body |
- | Required The connection request object to update. |
Schema 3.2
Connection Requests
| Name | Type | Format | Description |
|---|---|---|---|
Items |
array |
Connection Request | The result collection. |
NextPage |
string |
The URI of the next page of results, if any. |
Connection Request
| Name | Type | Format | Description |
|---|---|---|---|
firstName |
string |
- | The user's first name. |
ID |
string |
- | The unique identifier of the resource. |
lastModified |
string |
- | The date and time when the connection request was last modified. Format: UTC |
lastName |
string |
- | The user's last name. |
loyaltyNumber |
string |
- | The user's travel loyalty number. |
middleName |
string |
- | The user's middle name. |
requestToken |
string |
- | The request token. |
status |
string |
- | The status code representing the state of the connection request. |
URI |
string |
- | The URI to the resource. |
userId |
string |
- | The unique identifier of the user. |
emailAddresses |
UserEmailAddresses |
User Email Addresses | Email addresses associated with the user. |
User Email Addresses
| Name | Type | Format | Description |
|---|---|---|---|
email1 |
string |
- | The user's verified email address. |
email2 |
string |
- | The user's verified email address. |
email3 |
string |
- | The user's verified email address. |
email4 |
string |
- | The user's verified email address. |
email5 |
string |
- | The user's verified email address. |
Schema 3.0 (Deprecated)
Connection Requests
| Name | Type | Format | Description |
|---|---|---|---|
Items |
array |
Connection Request | The result collection. |
NextPage |
string |
The URI of the next page of results, if any. |
Connection Request
| Name | Type | Format | Description |
|---|---|---|---|
FirstName |
string |
- | The user's first name. |
ID |
string |
- | The unique identifier of the resource. |
LastModified |
string |
- | The date and time when the connection request was last modified. Format: UTC |
LastName |
string |
- | The user's last name. |
LoyaltyNumber |
string |
- | The user's travel loyalty number. |
MiddleName |
string |
- | The user's middle name. |
RequestToken |
string |
- | The request token. |
Status |
string |
- | The status code representing the state of the connection request. |
URI |
string |
- | The URI to the resource. |
Schema 3.1 (Deprecated)
Connection Requests
| Name | Type | Format | Description |
|---|---|---|---|
Items |
array |
Connection Request | The result collection. |
NextPage |
string |
The URI of the next page of results, if any. |
Connection Request
| Name | Type | Format | Description |
|---|---|---|---|
FirstName |
string |
- | The user's first name. |
ID |
string |
- | The unique identifier of the resource. |
LastModified |
string |
- | The date and time when the connection request was last modified. Format: UTC |
LastName |
string |
- | The user's last name. |
LoyaltyNumber |
string |
- | The user's travel loyalty number. |
MiddleName |
string |
- | The user's middle name. |
RequestToken |
string |
- | The request token. |
Status |
string |
- | The status code representing the state of the connection request. |
URI |
string |
- | The URI to the resource. |
EmailAddresses |
UserEmailAddresses |
User Email Addresses | Email addresses associated with the user. |
User Email Addresses
| Name | Type | Format | Description |
|---|---|---|---|
Email1 |
string |
- | The user's verified email address. |
Email2 |
string |
- | The user's verified email address. |
Email3 |
string |
- | The user's verified email address. |
Email4 |
string |
- | The user's verified email address. |
Email5 |
string |
- | The user's verified email address. |
Getting Started
Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.
- Overview
- Terminology
- Delivery model
- Access control
- Subscribing
- Endpoint Requirements
- Authentication
- Service behavior
Event Subscription Service (ESS)
The Event Subscription Service (ESS) implements Publish/Subscribe pattern using principles of Event Driven Architecture in SAP Concur. It allows clients and partners to be notified through web services when certain actions take place in connected SAP Concur companies. When the business/system event occurs in SAP Concur, ESS sends that event to the configured endpoint with relevant information.
ESS Terminology
- Event - a state of business/system object or entity. Always has EventType that represents a type of entity change or specific state in a workflow. Example: Report Created, Report Submitted, etc
- Topic - a stream of events of business/system object or entity. Example: Concur.user, Concur.expense.report, Concur.travel.request. There is always a topic owner in Concur, it can be team, product or system.
- Subscription - a topic consumer. Each subscription has a topic it is subscribed to.
- Webhook - an ESS application that uses subscription and delivers events to the endpoint.
ESS Delivery model
It is important to remember that ESS doesn't have any API that you can call for SAP Concur events, ESS delivers events to your endpoint.
It uses an outbound callout where SAP Concur calls a public facing URL provided by client or partner, which is a web server hosted by the third-party developer or client.
The application endpoint can also use the related web services to retrieve or send SAP Concur data. For example, an event may be generated when a request for travel is submitted. The application endpoint may then leverage data from the event, such as the request ID, to retrieve the relevant travel request record from the published Request APIs.
Access control
ESS is requiring a caller to have a proper JWT and scopes, for more details please refer our wiki A caller must have types of scopes
ESS API level scope "events.topic.read" is required to be able to access ESS API
Resource level scope example "expense.request.read" is required to be able to access "expense.request" topic and to be able to create subscriptions to that topic
All required scopes can be requested for a caller Application by Partner Enablement team.
Subscribing your endpoint
In order to begin receiving events, you must first subscribe to the relevant topic(s) for your application.
To subscribe to an event, you must work with your relevant SAP Concur technical contact; for partners, please work with your technical enablement contact. For customers, your web services consultant will subscribe on your behalf to the relevant topic(s).
Endpoint Requirements
The Event Subscription Service provides guaranteed at least once event delivery. This is accomplished through retrying posting of the event payload to the subscribers' endpoint until the response indicates successful receipt. The expected acknowledgment max for a request to the subscribers' endpoint is 30 seconds. The service will attempt posting to the endpoint and then back-off and retry until the subscriber endpoint responds with delivered or not accepted, the service will retry at least 3 days and skip to the next event after unsuccessful delivery. SAP Concur suggests the subscriber to consider following:
* Endpoint response time requirements depend on the topic throughput. Please contact topic owner to calculate acceptable throughput, generally we recommend to keep response time as low as possible (< 3 seconds)
* We highly recommend to implement queue behind the subscriber' endpoint in order to keep response time as low as possible
* The subscriber must maintain reasonable uptime to support the requirements of the integration scenario.
* We multithreaded application to deliver events to your endpoint. 24 threads by default.
* Your HTTPS server endpoint must be accessible from the public web with a non-self-signed certificate. The certificate should be signed by a known Certificate Authority and should be reachable through DNS.
ESS Authentication
There are several way how you can be sure that your endpoint being accessed by our service.
* We will always use the same client x509 certificate. Common name is "CN=webhook.api.concursolutions.com,O=Concur Technologies\, Inc.,L=Bellevue,ST=Washington,C=US" and certificate serial number is "0AE315A13AB9EF8CADB9A46255C87283"
* We will always use Digital Signature, it will be supplied in request header "Concur-Signature". If you decide to use this authentication method you will need our
PUBLIC KEY
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxS1LsXrEWEEMPooLHa4r
osCAnmkO3HaBAk0YcsDMR6hQeuQNLqRWP65TpbfTbKWmZ22Hzep3Ekhs1qvSZgI+
iq/bnVeDhkcD+LqVQGP+7fyE0E0bO96FOzMmtbRet4wAiiE9+uw5GmZfg+fRG3yI
y2N5u5p7VHJ1RwNugrIUQjhrLvZc+lhqR/aKTxQCQ5CGAgLZIcr3FIWCWrSBMK3d
Wy3KI+qe3ZX0STrCCNxl2UFnuuAa2RZZ2j4QtWHlNkyK+UEup+cGkvpc1XrT7anL
HlbTP6jE7MqB5sJ9r2EEzrJzJZjD13UqlzvI61tTC8SKpuk5AEaSsUV7RKlKUCjB
8wIDAQAB
-----END PUBLIC KEY-----
ESS Behavior
The Event Subscription service has the following characteristics from the subscriber perspective:
- Requests will come from us.api.concursolutions.com, emea.api.concursolutions.com or cn.api.concursolutions.com
- Connection will always be established using client x509 certificate
- Requests will always have digital signature
- Requests will be re-tried when subscriber responds with HTTP Response Code(s): 5xx, 401, 403 and 429
- Requests will not be re-tried when subscriber responds with HTTP Response Code(s):
- 2xx – Indicates successful receipt of the event
- 4xx – Indicates posted event is unexpected or incorrectly formatted
- Request will be retried until delivery OR event retention period expiry
- Event retention period is 72 hours from the time of event being published
- Events are not archived, but all of the event delivery attempts/responses are logged and retained for 30 days
Event Subscription Management
Event Subscription Management
Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.
- Access Control (JWT)
- Browse available topics
- Create a subscription
- Verify your subscription
- Browse existing subscriptions
- Delete your subscription
- Request Example
1. Access Control (JWT)
The Event Subscription Service (ESS) APIs uses the standard Concur OAuth2 Framework for Authentication and Authorization via JSON Web Token (JWT).
The authentication is done by using a JWT which represents the event subscriber. This can be obtained by calling the Client Credentials grant type using your OAuth2 credentials. The JWT generated by this grant will have a JWT Type of App where your Application ID is the Subject of the Token.
For authorization, the Application needs to contain the scope events.topic.read in order to access the ESS APIs. This scope will be inherited by the JWT during the Client Credentials Grant which is then checked by the ESS API.
Pass the JWT in the Post Header when making calls to the ESS API:
Authorization: Bearer <JWT>
The Client Credentials JWT has a lifetime of 60 minutes and can only be obtained again via the Client Credentials Grant.
2. Browse available topics
Before you create any subscription you need to verify that you have sufficient access to the topic. If that request returns empty you need to get in touch with your assigned contact from SAP Concur to set proper scopes to your Concur Oauth2 Application.
Request
GET /events/v4/topics
Response
json
["public.test"]
3. Create a subscription
To create a subscription you need to
1. know and have sufficient access to the topic
1. get your receiving endpoint running, endpoint
requirements
1. come up with unique name (id) of your subscription. Subscription names are globally unique, and you will get an error if name is already occupied.
1. set filter to .* (regexp syntax), you can use it later to filter out unwanted types of events
Request
PUT /events/v4/subscriptions/webhook
json
{
"id": "my-unique-subscription-id",
"filter": ".*",
"topic": "public.test",
"webHookConfig": {
"endpoint": "https://www.concuress.com/sub/my-valid-endpoint"
}
}
Response
json
{"message":"Subscription 'my-unique-subscription-id' saved successfully"}
4. Verify your subscription
You can always request a configuration of your subscription. You might notice that your subscription contains some more parameters that you can not modify for security reasons, but can use them for troubleshooting purposes. - applicationId - identifies your Concur Application as an owner of that subscription - companyIds - a list of UUIDs of companies that allowed your Applicaion to access their data, the process of connecting Concur company to your application is described here (link) - groups and scope - are used for complex access control scenarios
Request
GET /events/v4/subscriptions/my-unique-subscription-id
Response
json
[
{
"id": "my-unique-subscription-id",
"topic": "public.test",
"filter": ".*",
"webHookConfig": {
"endpoint": "https://www.concuress.com/sub/my-valid-endpoint"
},
"applicationId": "dabd27f0-23e7-415d-b5e5-19a7dbe4fb4d",
"scope": "",
"groups": [],
"companyIds": []
}
]
5. Browse existing subscriptions
If you happen to forget your subscription name/id, you can always retrieve all of your subscriptions by calling next endpoint:
Request
GET /events/v4/subscriptions
Response
json
[
{
"id": "my-second-unique-subscription-id",
"topic": "public.test",
"filter": ".*",
"webHookConfig": {
"endpoint": "https://www.concuress.com/sub/my-second-valid-endpoint"
},
"applicationId": "dabd27f0-23e7-415d-b5e5-19a7dbe4fb4d",
"scope": "",
"groups": [],
"companyIds": []
},
{
"id": "my-unique-subscription-id",
"topic": "public.test",
"filter": ".*",
"webHookConfig": {
"endpoint": "https://www.concuress.com/sub/my-valid-endpoint"
},
"applicationId": "dabd27f0-23e7-415d-b5e5-19a7dbe4fb4d",
"scope": "",
"groups": [],
"companyIds": []
}
]
6. Delete your subscription
Request
DELETE /events/v4/subscriptions/my-unique-subscription-id
Response
json
{
"message": "Subscription 'my-unique-subscription-id' marked for deletion"
}
6. Request Example
HEADERS
PUT /events/v4/subscriptions/webhook HTTP/1.1
Content-Type: application/json
Concur-Correlationid: something-unique-and-trackable
Authorization: Bearer eyJ0e*****MY-SECRET-JWT-HERE********
Accept: */*
Cache-Control: no-cache
Host: www-us.api.concursolutions.com
Accept-Encoding: gzip, deflate
Connection: keep-alive
BODY
{
"id": "my-unique-subscription-example",
"filter": ".*",
"topic": "public.test",
"webHookConfig": {"endpoint": "https://www.concuress.com/sub/my-unique-endpoint" }
}
CURL Code
curl -X PUT \
https://www-us.api.concursolutions.com/events/v4/subscriptions/webhook \
-H 'Accept: */*' \
-H 'Accept-Encoding: gzip, deflate' \
-H 'Authorization: Bearer eyJ0e*****MY-SECRET-JWT-HERE********' \
-H 'Cache-Control: no-cache' \
-H 'Concur-Correlationid: something-unique-and-trackable' \
-H 'Connection: keep-alive' \
-H 'Content-Type: application/json' \
-H 'Host: www-us.api.concursolutions.com' \
-H 'cache-control: no-cache' \
-d '{
"id": "my-unique-subscription-example-2",
"filter": ".*",
"topic": "public.test",
"webHookConfig": {
"endpoint": "https://www.concuress.com/sub/my-unique-endpoint"
}
}'
Getting Started
Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.
Overview
The Event Subscription Service (ESS) allows clients and partners to choose to be notified through web services when certain actions take place in connected SAP Concur companies. When the event occurs, SAP Concur generates a notification and sends a request to the configured endpoint with event information.
This callout differs from the standard Concur web services in the following ways:
It uses an outbound callout where SAP Concur calls a public facing URL provided by the application connector, which is a web server hosted by the third-party developer or client.
The application connector can also use the related web services to retrieve or send SAP Concur data. For example, an event may be generated when a request for travel is submitted. The application connector may then leverage data from the event, such as the request ID, to retrieve the relevant travel request record from the published Request APIs.
Subscribing
In order to begin receiving events, you must first subscribe to the relevant topic(s) for your application connector.
To subscribe to an event, you must work with your relevant SAP Concur technical contact; for partners, please work with your technical enablement contact. For customers, your web services consultant will subscribe on your behalf to the relevant topic(s).
You must provide an HTTPS server endpoint that will accept the event payload described below.
Your HTTPS server endpoint must accessible from the public web with a non-self-signed certificate. The certificate should be signed by a known Certificate Authority and should be reachable through DNS.
Endpoint Requirements
The Event Subscription Service provides guaranteed at least once event delivery. This is accomplished through retrying posting of the event payload to the subscribers' endpoint until the response indicates successful receipt. The expected acknowledgment max for a request to the subscribers' endpoint is 30 seconds. The service will attempt posting to the endpoint and then back-off and retry until the subscriber endpoint responds with delivered or not accepted. SAP Concur suggests the subscriber endpoint implement the following behavior characteristics: * Ensure endpoint responds as quickly as possible (< 3 seconds) * The subscriber must maintain reasonable uptime to support the requirements of the integration scenario * If the subscriber must have durability of delivered events these must be persisted on the subscriber side * If the subscriber action on the event is non-idempotent or expensive guard against a duplicate event by checking the event Id has not already been processed.
Event Subscription Service (ESS) Behavior
The Event Subscription service has the following characteristics from the subscriber perspective:
- Requests will come from us.api.concursolutions.com, emea.api.concursolutions.com or cn.api.concursolutions.com
- Requests will be re-tried when subscriber responds with HTTP Response Code(s): 5xx, 401, 403 and 429
- Requests will not be re-tried when subscriber responds with HTTP Response Code(s):
- 2xx – Indicates successful receipt of the event
- 4xx – Indicates posted event is unexpected or incorrectly formatted
- Request will be retried until delivery OR event retention period expiry
- Event retention period is 72 hours from the time of event being published
- Events are not archived, but of the event delivery attempts/responses are logged and retained a (period of time)
Travel Search Event
Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.
Overview
The topic 'concur.travel.search' provides travel search information. Subscribers to this event will receive search criteria for travel searches performed within the SAP Concur online booking tool.
This event is relevant for applications that are interacting with travelers before they book their trip such as applications that context to the traveler regarding company policy, preferences, or general compliance requirements for booking travel.
Schema
Air
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
GUID |
Uniquely identifies the event. |
correlationId |
string |
GUID |
Uniquely identifies the air search request. |
eventType |
string |
- | Identifies the search event type. Supported values: travelSearchAir |
topic |
string |
- | Topic for subscription. Supported values: concur.travel.search |
subTopic |
string |
- | Identifies a sub topic. Supported values: airshop.v1.schedule, airshop.v1.price |
timeStamp |
string |
date/time |
Search event time in UTC. |
facts |
object |
Air Search Facts | Facts for air search. |
Air Search Facts
| Name | Type | Format | Description |
|---|---|---|---|
companyId |
string |
GUID |
Uniquely identifies the company of the traveler. |
userId |
string |
GUID |
Uniquely identifies the user performing the search. Note: In the event travel is booked by an arranger, this will be the traveler's ID. In cases where a profiled user is booking on behalf of a non profiled guest, this will be the user performing the search. |
arrangerUserId |
string |
GUID |
If the user is also the traveler, this value will be the same as the userID above. If an arranger is booking on behalf of the traveler, this will uniquely identify the user arranging the trip. |
searchLegs |
string |
- | Type of air search. Supported values: RoundTrip, MultiSeg, OneWay |
isGuestBooking |
boolean |
- | Identifies if the booking is a guest. |
isFlexFaring |
boolean |
- | Identifies if search is for flex faring. |
segments |
array |
Air Search Segment | List of segments for search. |
numberOfTravelers |
integer |
- | Number of travelers. |
classOfTrip |
string |
- | Selected cabin class. Supported values: F = First Class, C = Business Class, W = Premium Economy, Y = Economy Class |
airCarriers |
array |
- | If the user filters for individual carriers, this list will be populated with the IATA airline carrier codes. Example: AA, VA, LH |
Air Search Segment
| Name | Type | Format | Description |
|---|---|---|---|
departures |
array |
City | List of departure airports selected by the user. A user can select a city area/hub as point of departure, which will result in an array of multiple airports. |
arrivals |
array |
City | List of arrival airports selected by the user. A user can select a city area/hub as point of arrival, which will result in an array of multiple airports. |
departureDate |
string |
YYYY-MM-DD |
Date traveler will depart from the point of departure, local time. Either the departure date/time, or the arrival date/time will be populated. |
departureTime |
string |
HH:MM AM/PM |
Departure time, in local time. Either the departure date/time, or the arrival date/time will be populated. |
departureTimeWindow |
integer |
- | Time window (+/-) around selected departure time, in hours. Either the departure date/time, or the arrival date/time will be populated. |
arrivalDate |
string |
YYYY-MM-DD |
Date on which the traveler will arrive at the destination, in local time. Either the departure date/time, or the arrival date/time will be populated. |
arrivalTime |
string |
HH:MM AM/PM |
Time at which the traveler will arrive at the destination, in local time. Either the departure date/time, or the arrival date/time will be populated. |
arrivalTimeWindow |
integer |
- | Time window (+/-) around selected arrival time, in hours. Either the departure date/time, or the arrival date/time will be populated. |
City
| Name | Type | Format | Description |
|---|---|---|---|
cityName |
string |
- | Name of the city. Example: Frankfurt |
cityIATACode |
string |
- | IATA code of the city. Example: FRA. Note: If the user searches for a group of airports (e.g. Los Angeles area airports), this code will not be IATA standard. In this case, the city name should be used. |
Hotel
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
GUID |
Uniquely identifies the event. |
correlationId |
string |
GUID |
Uniquely identifies the hotel search request. |
eventType |
string |
- | Identifies the search event type. Supported values: travelSearchHotel |
topic |
string |
- | Topic for subscription. Supported values: concur.travel.search |
subTopic |
string |
- | Identifies sub-topic. Supported values: hotelshop.v1.price |
timeStamp |
string |
date/time |
Search event time in UTC. |
facts |
object |
Hotel Search Facts | Facts for hotel search. |
Hotel Search Facts
| Name | Type | Format | Description |
|---|---|---|---|
companyId |
string |
GUID |
Uniquely identifies the company of the traveler. |
userId |
string |
GUID |
Uniquely identifies the user performing the search. Note: In the event travel is booked by an arranger, this will be the traveler’s ID. In cases where a profiled user is booking on behalf of a non-profiled guest, this will be the user performing the search. |
refPointLatitude |
number |
double |
Reference point for the search latitude. |
refPointLongitude |
number |
double |
Reference point for the search longitude. |
refPointName |
string |
- | Reference point for the search name. |
radiusDistance |
integer |
- | Distance around the reference point as selected by the user. |
distanceUnit |
string |
- | Unit for radius distance. Supported values: Mile, Kilometer |
checkInDate |
string |
YYYY-MM-DD |
Check in date, in local time. |
checkOutDate |
string |
YYYY-MM-DD |
Check out date, in local time. |
Sample Events
Air
Sample roundtrip air search
{
"id": "00e4aeb3-d181-4881-89b1-0d0b5418968f",
"correlationId": "51AB4E74-1287-4B20-87FB-98A93CE4CEEB",
"eventType": "travelSearchAir",
"topic": "concur.travel.search",
"timeStamp": "2018-10-15T14:19:06.752Z",
"data": null,
"subtopic": null,
"facts": {
"companyId": "",
"userId": "",
"arrangerUserId": "",
"searchLegs": "RoundTrip",
"isGuestBooking": false,
"isFlexFaring": false,
"segments": [
{
"departures": [
"LHR"
],
"arrivals": [
"FRA"
],
"departureDate": "1/15/2019",
"departureTime": "9:00 AM",
"departureTimeWindow": 3,
"arrivalDate": null,
"arrivalTime": null,
"arrivalTimeWindow": null
},
{
"departures": [
"FRA"
],
"arrivals": [
"LHR"
],
"departureDate": "1/16/2019",
"departureTime": "3:00 PM",
"departureTimeWindow": 3,
"arrivalDate": null,
"arrivalTime": null,
"arrivalTimeWindow": null
}
],
"numberOfTravelers": 1,
"classOfTrip": null,
"airCarriers": null
}
}
Custom List Items
Custom list fields are included in many of the web services calls and they require some special consideration.
Value
When posting a list item, the list item code should be sent as the value, not the list item name. The code is returned in the levelxcode element of the Get List Items function.
Posting Connected List Items
There are two types of custom lists: Simple lists and Connected (multi-level) lists. If the list is a connected list, the list fields must be sent in sequential order, from parent to the lowest level child list item, as they are configured in the connected list definition.
Example: If your connected list uses Custom5 for the first level, Custom10 for the second level and Custom2 for the third level, you must send the XML elements for the custom fields in that order:
<Custom5>FirstValueCode</Custom5>
<Custom10>SecondValueCode</Custom10>
<Custom2>ThirdValueCode</Custom2>
Common Issues
Developers that post custom list item values can encounter errors when they post a list item that does not exist in the SAP Concur database. This can happen when the list item import hasn't been completed or hasn't run recently. If the posted list item code does not match an existing list item, the post may result in bad data. Use the List Item web service to ensure that the list items you are posting are present in the Concur database.
List Item v3
This API has been deprecated.
Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.
Learn more in the API Lifecycle & Deprecation Policy.
The SAP Concur List Item API provides an automated solution to clients who would like to add, update, or delete list items. Use of the API is subject to some limitations on the volume of List data. You may need to manage the initial load of large volumes of data via a file import due to capacity limitations. This is also true if ongoing maintenance of List values involves a large volume.
- Retrieve all list items based on the search criteria
- Retrieve a list item by ID
- Create a new list item
- Update a list item
- Delete a list item
- Schema
Version
3.0
1.0 documentation is available here
Retrieve All List Items Based on the Search Criteria
GET /api/v3.0/common/listitems
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
limit |
Int32 |
query |
The number of records to return. The default is 25 and the maximum is 100. |
offset |
string |
query |
The start of the page offset. The default is from the beginning. |
listId |
string |
query |
The unique identifier for the list this item is a member. |
name |
string |
query |
The name of the listItem. Text Max length: 64. |
parentId |
string |
query |
The unique identifier of this item's parent. Is empty when there is no parent. |
level1Code |
string |
query |
The item code for the first level of the list. All lists have at least a Level1Code. Text maximum 32 characters |
level2Code |
string |
query |
The item code for the second level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters |
level3Code |
string |
query |
The item code for the third level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters |
level4Code |
string |
query |
The item code for the fourth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters |
level5Code |
string |
query |
The item code for the fifth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters |
level6Code |
string |
query |
The item code for the sixth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters |
level7Code |
string |
query |
The item code for the seventh level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters |
level8Code |
string |
query |
The item code for the eighth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters |
level9Code |
string |
query |
The item code for the ninth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters |
level10Code |
string |
query |
The item code for the tenth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters |
Retrieve a List Item by ID
GET /api/v3.0/common/listitems/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required The unique identifier for the listItem. |
listId |
string |
query |
The unique identifier for the list this item is a member. |
Create a New List Item
POST /api/v3.0/common/listitems
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
content |
- | body |
Required List item object to create. |
Update a List Item
PUT /api/v3.0/common/listitems/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required The unique identifier for the list item. |
content |
- | body |
Required The list item object to update. |
Delete a List Item
DELETE /api/v3.0/common/listitems/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required The unique identifier of the listitem to delete |
listId |
string |
query |
Required The unique identifier of the list associated with a listitem to be deleted |
Schema
List Items
| Name | Type | Format | Description |
|---|---|---|---|
Items |
array |
List Item | The result collection. |
NextPage |
string |
- | The URI of the next page of results, if any. |
List Item
| Name | Type | Format | Description |
|---|---|---|---|
ID |
string |
- | The unique identifier of the resource. |
Level10Code |
string |
- | The item code for the tenth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters |
Level1Code |
string |
- | The item code for the first level of the list. All lists have at least a Level1Code. Text maximum 32 characters |
Level2Code |
string |
- | The item code for the second level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters |
Level3Code |
string |
- | The item code for the third level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters |
Level4Code |
string |
- | The item code for the fourth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters |
Level5Code |
string |
- | The item code for the fifth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters |
Level6Code |
string |
- | The item code for the sixth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters |
Level7Code |
string |
- | The item code for the seventh level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters |
Level8Code |
string |
- | The item code for the eighth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters |
Level9Code |
string |
- | The item code for the ninth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters |
ListID |
string |
- | The unique identifier for the list this item is a member. |
Name |
string |
- | The name of item. Text maximum 64 characters |
ParentID |
string |
- | The unique identifier of this item's parent. Is empty when there is no parent. |
URI |
string |
- | The URI to the resource. |
List Item v4
The SAP Concur List Item API provides an automated solution to clients who would like to retrieve and add list items. Use of the API is subject to some limitations on the volume of list data. You may need to manage the initial load of large volumes of data via a file import due to capacity limitations. This is also true if ongoing maintenance of list values involves a large volume.
Limitations: This API is only available to partners who have been granted access by SAP Concur. Access to this documentation does not provide access to the API.
Contents
- Process Flow
- Products and Editions
- Scope Usage
- Access Token Usage
- Retrieve a List Item by ID
- Create a List Item
- Update a List Item
- Delete a List Item
- Delete a List Item from a List
- Retrieve Children of a List Item
- Retrieve Children of a List Item by List
- Retrieve First Level Children of a List
- Filtering
- Schema
Prior Versions
Process Flow

Products and Editions
- Concur Expense Professional Edition
- Concur Expense Standard Edition
- Concur Invoice Professional Edition
- Concur Invoice Standard Edition
- Concur Request Professional Edition
- Concur Request Standard Edition
Scope Usage
| Name | Description | Endpoint |
|---|---|---|
spend.listitem.read |
Read-only access to spend list items. | GET |
spend.listitem.write |
Read and write access to spend list items. | GET, POST, PUT |
spend.listitem.delete |
Delete capabilities for spend list items. | DELETE |
Dependencies
Users must be an Expense, Invoice, Shared or Request Configuration Administrator in order to perform POST and PUT actions.
Access Token Usage
This API supports both company level and user level access tokens.
Retrieve a List Item by ID
Retrieve a list item by ID.
Scopes
spend.listitem.read - Refer to Scope Usage for full details.
Request
URI
Template
GET /list/v4/items/{itemId}
Parameters
| Name | Type | Description |
|---|---|---|
Accept-Language |
string |
Language code. Default: Company defined default language |
itemId |
string |
Required The unique identifier of the list item. |
Headers
Response
Status Codes
- 200 OK
- 400 Bad Request - Company does not exist
- 401 Unauthorized
- 404 Not Found
- 500 Internal Server Error
Headers
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7230 Content-Length
- RFC 7231 Content-Type
- RFC 7231 Date
- RFC 7232 ETag
- RFC 7234 Cache-Control
Payload
Example
Request
GET https://us.api.concursolutions.com/list/v4/items/{itemId}
Accept: application/json
Accept-Language: en
Authorization: Bearer {token}
Response
HTTP/1.1 200
concur-correlationid: 663d7795-fc21-4d98-ba31-87be20aeacd2
content-length: 360
content-type: application/json;charset=UTF-8
date: Wed, 08 Jul 2020 14:07:25 GMT
etag: "0950be10ca5a9f5069898e2468db6e137"
cache-control: no-cache, private
{
"id": "63b7fbd9-ae08-0840-abdb-62b0b9160081",
"code": "ITEM-SECOND LEVEL ITEM",
"shortCode": "SECOND LEVEL ITEM",
"value": "SECOND LEVEL ITEM",
"parentId": "7c6d0435-c4d1-8b48-8492-7e7b625e148d",
"level": 2,
"isDeleted": false,
"lists": [
{
"id": "80edb3fa-c15e-a34a-b97f-f2ec291ab44f",
"hasChildren": false
}
]
}
Create a List Item
Create a list item with the provided request body.
Scopes
spend.listitem.write - Refer to Scope Usage for full details.
Request
URI
Template
POST /list/v4/items
Parameters
| Name | Type | Description |
|---|---|---|
Accept-Language |
string |
Language code. Default: Company defined default language |
listItem |
- | Required List Item object that is created for the company. |
Headers
Payload
Response
Status Codes
- 201 Created
- 400 Bad Request
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found
- 415 Unsupported Media Type
- 500 Internal Server Error
Headers
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7230 Content-Length
- RFC 7231 Content-Type
- RFC 7231 Date
- RFC 7231 Location
- RFC 7234 Cache-Control
Payload
Example
Request
POST https://us.api.concursolutions.com/list/v4/lists
Accept: application/json
Accept-Language: en
Content-Type: application/json
Authorization: Bearer {token}
Example 1 (create first level list item):
json
{
"listId": "80edb3fa-c15e-a34a-b97f-f2ec291ab44f",
"shortCode": "ITEM",
"value": "ITEM"
}
Example 2 (create second level list item by parent list item ID):
json
{
"listId": "80edb3fa-c15e-a34a-b97f-f2ec291ab44f",
"parentId": "7c6d0435-c4d1-8b48-8492-7e7b625e148d",
"shortCode": "SECOND LEVEL ITEM",
"value": "SECOND LEVEL ITEM"
}
Example 3 (create second level list item by parent list item code):
json
{
"listId": "80edb3fa-c15e-a34a-b97f-f2ec291ab44f",
"parentCode": "ITEM",
"shortCode": "SECOND LEVEL ITEM",
"value": "SECOND LEVEL ITEM"
}
Response
HTTP/1.1 201
concur-correlationid: 85b8deb7-db84-4dfb-bdca-d4bccb2ef06e
content-length: 282
content-type: application/json;charset=UTF-8
date: Wed, 08 Jul 2020 13:47:25 GMT
location: http://localhost:5000/list/v4/items/7c6d0435-c4d1-8b48-8492-7e7b625e148d
cache-control: no-cache, private
Example 1:
json
{
"id": "7c6d0435-c4d1-8b48-8492-7e7b625e148d",
"code": "ITEM",
"shortCode": "ITEM",
"value": "ITEM",
"parentId": null,
"level": 1,
"isDeleted": false,
"lists": [
{
"id": "80edb3fa-c15e-a34a-b97f-f2ec291ab44f",
"hasChildren": false
}
]
}
Example 2 and Example 3:
json
{
"id": "63b7fbd9-ae08-0840-abdb-62b0b9160081",
"code": "ITEM-SECOND LEVEL ITEM",
"shortCode": "SECOND LEVEL ITEM",
"value": "SECOND LEVEL ITEM",
"parentId": "7c6d0435-c4d1-8b48-8492-7e7b625e148d",
"level": 2,
"isDeleted": false,
"lists": [
{
"id": "80edb3fa-c15e-a34a-b97f-f2ec291ab44f",
"hasChildren": false
}
]
}
Update a List Item
Update a list item with provided request body.
Scopes
spend.listitem.write - Refer to Scope Usage for full details.
Request
URI
Template
PUT /list/v4/items/{itemId}
Parameters
| Name | Type | Description |
|---|---|---|
Accept-Language |
string |
Language code. Default: Company defined default language |
itemId |
string |
Required The unique identifier of the list item. |
listItem |
- | Required List Item object that is updated. |
Headers
Payload
Response
Status Codes
- 200 OK
- 400 Bad Request - Company does not exist
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found
- 415 Unsupported Media Type
- 500 Internal Server Error
Headers
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7230 Content-Length
- RFC 7231 Content-Type
- RFC 7231 Date
- RFC 7234 Cache-Control
Payload
Example
Request
PUT https://us.api.concursolutions.com/list/v4/items/7c6d0435-c4d1-8b48-8492-7e7b625e148d
Accept: application/json
Accept-Language: en
Content-Type: application/json
Authorization: Bearer {token}
{
"shortCode": "ITEM",
"value": "ITEM UPDATED"
}
Response
HTTP/1.1 200
concur-correlationid: 27abed5d-20cc-4edf-81b6-3e2dbf70ba39
content-length: 289
content-type: application/json;charset=UTF-8
date: Wed, 08 Jul 2020 14:16:21 GMT
cache-control: no-cache, private
{
"id": "7c6d0435-c4d1-8b48-8492-7e7b625e148d",
"code": "ITEM",
"shortCode": "ITEM",
"value": "ITEM UPDATED",
"parentId": null,
"level": 1,
"isDeleted": false,
"lists": [
{
"id": "80edb3fa-c15e-a34a-b97f-f2ec291ab44f",
"hasChildren": true
}
]
}
Delete a List Item
Delete a list item by list item ID. A list item shared between multiple lists will be deleted from all lists.
Scopes
spend.listitem.delete - Refer to Scope Usage for full details.
Request
URI
Template
DELETE /list/v4/items/{itemId}
Parameters
| Name | Type | Description |
|---|---|---|
itemId |
string |
Required The unique identifier of the list item. |
Headers
Response
Status Codes
- 204 No Content
- 400 Bad Request - Company does not exist
- 401 Unauthorized
- 403 Forbidden
- 500 Internal Server Error
Headers
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7231 Date
- RFC 7234 Cache-Control
Payload
Example
Request
DELETE https://us.api.concursolutions.com/list/v4/items/7c6d0435-c4d1-8b48-8492-7e7b625e148d
Accept: application/json
Authorization: Bearer {token}
Response
HTTP/1.1 204
concur-correlationid: d92ab0c7-510b-4730-99a8-14a79ad99b7c
date: Wed, 08 Jul 2020 14:16:21 GMT
cache-control: no-cache, private
Delete a List Item from a List
Delete a list item by list item ID from a particular list. This enables deleting a shared list item from one list, not all lists.
Scopes
spend.listitem.delete - Refer to Scope Usage for full details.
Request
URI
Template
DELETE /list/v4/lists/{listId}/items/{itemId}
Parameters
| Name | Type | Description |
|---|---|---|
listId |
string |
Required The unique identifier of the list. |
itemId |
string |
Required The unique identifier of the list item. |
Headers
Response
Status Codes
- 204 No Content
- 400 Bad Request - Company does not exist
- 401 Unauthorized
- 403 Forbidden
- 500 Internal Server Error
Headers
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7231 Date
- RFC 7234 Cache-Control
Payload
Example
Request
DELETE https://us.api.concursolutions.com/list/v4/lists/80edb3fa-c15e-a34a-b97f-f2ec291ab44f/items/7c6d0435-c4d1-8b48-8492-7e7b625e148d
Accept: application/json
Authorization: Bearer {token}
Response
HTTP/1.1 204
concur-correlationid: d92ab0c7-510b-4730-99a8-14a79ad99b7c
date: Wed, 08 Jul 2020 14:16:21 GMT
cache-control: no-cache, private
Retrieve Children of a List Item
Retrieve the direct children for a given list item.
Scopes
spend.listitem.read - Refer to Scope Usage for full details.
Request
URI
Template
GET /list/v4/items/{itemId}/children?page={page}&sortBy={sortBy}
Parameters
| Name | Type | Description |
|---|---|---|
Accept-Language |
string |
Language code. Default: Company defined default language |
hasChildren |
boolean |
If true, displays items with children. |
isDeleted |
boolean |
If true, displays deleted items. |
itemId |
string |
Required The unique identifier of the list item. |
page |
integer |
Page number starting from 1. Default: 1 |
shortCode |
string |
Filter capabilities for shortCode. |
shortCodeOrValue |
string |
Filter capabilities for value or shortCode. |
sortBy |
string |
Field to sort by. Supported values: value, shortCode. Default: value |
sortDirection |
string |
Sort direction. Supported values: asc, desc |
value |
string |
Filter capabilities for value. |
Headers
Response
Status Codes
Headers
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7230 Content-Length
- RFC 7231 Content-Type
- RFC 7231 Date
- RFC 7232 ETag
- RFC 7234 Cache-Control
Payload
Example
Request
GET https://us.api.concursolutions.com/list/v4/items/7c6d0435-c4d1-8b48-8492-7e7b625e148d/children?page=1&sortBy=value
Accept: application/json
Accept-Language: en
Authorization: Bearer {token}
Response
HTTP/1.1 200
concur-correlationid: 50dcec14-c984-479c-84e2-186a7e62f87e
content-length: 449
content-type: application/json;charset=UTF-8
date: Wed, 08 Jul 2020 14:27:13 GMT
etag: "05cb0f0ed5a73bedf1e8cd4171e360e41"
cache-control: no-cache, private
{
"links": [],
"content": [
{
"id": "63b7fbd9-ae08-0840-abdb-62b0b9160081",
"code": "ITEM-SECOND LEVEL ITEM",
"shortCode": "SECOND LEVEL ITEM",
"value": "SECOND LEVEL ITEM",
"parentId": "7c6d0435-c4d1-8b48-8492-7e7b625e148d",
"level": 2,
"isDeleted": false,
"lists": [
{
"id": "80edb3fa-c15e-a34a-b97f-f2ec291ab44f",
"hasChildren": false
}
]
}
],
"page": {
"size": 100,
"totalElements": 1,
"totalPages": 1,
"number": 1
}
}
Retrieve Children of a List Item by List
Retrieve the direct children for a given list item in a particular list. For a list item shared between multiple lists, this API enables retrieving children from a particular list.
Scopes
spend.listitem.read - Refer to Scope Usage for full details.
Request
URI
Template
GET /list/v4/lists/{listId}/items/{itemId}/children?page={page}&sortBy={sortBy}
Parameters
| Name | Type | Description |
|---|---|---|
Accept-Language |
string |
Language code. Default: Company defined default language |
hasChildren |
boolean |
If true, displays items with children. |
isDeleted |
boolean |
If true, displays deleted items. |
itemId |
string |
Required The unique identifier of the list item. |
listId |
string |
Required The unique identifier of the list. |
page |
integer |
Page number starting from 1. Default: 1 |
shortCode |
string |
Filter capabilities for shortCode. |
shortCodeOrValue |
string |
Filter capabilities for value or shortCode. |
sortBy |
string |
Field to sort by. Supported values: value, shortCode. Default: value |
sortDirection |
string |
Sort direction. Supported values: asc, desc |
value |
string |
Filter capabilities for value. |
Headers
Response
Status Codes
Headers
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7230 Content-Length
- RFC 7231 Content-Type
- RFC 7231 Date
- RFC 7232 ETag
- RFC 7234 Cache-Control
Payload
Example
Request
GET https://us.api.concursolutions.com/list/v4/lists/80edb3fa-c15e-a34a-b97f-f2ec291ab44f/items/7c6d0435-c4d1-8b48-8492-7e7b625e148d/children?page=1&sortBy=value
Accept: application/json
Accept-Language: en
Authorization: Bearer {token}
Response
HTTP/1.1 200
concur-correlationid: 50dcec14-c984-479c-84e2-186a7e62f87e
content-length: 449
content-type: application/json;charset=UTF-8
date: Wed, 08 Jul 2020 14:27:13 GMT
etag: "05cb0f0ed5a73bedf1e8cd4171e360e41"
cache-control: no-cache, private
{
"links": [],
"content": [
{
"id": "63b7fbd9-ae08-0840-abdb-62b0b9160081",
"code": "ITEM-SECOND LEVEL ITEM",
"shortCode": "SECOND LEVEL ITEM",
"value": "SECOND LEVEL ITEM",
"parentId": "7c6d0435-c4d1-8b48-8492-7e7b625e148d",
"level": 2,
"isDeleted": false,
"lists": [
{
"id": "80edb3fa-c15e-a34a-b97f-f2ec291ab44f",
"hasChildren": false
}
]
}
],
"page": {
"size": 100,
"totalElements": 1,
"totalPages": 1,
"number": 1
}
}
Retrieve First Level Children Items of a List
Retrieves the first level list items for a given List ID.
Scopes
spend.listitem.read - Refer to Scope Usage for full details.
Request
URI
Template
GET /list/v4/lists/{listId}/children?page={page}&sortBy={sortBy}
Parameters
| Name | Type | Description |
|---|---|---|
Accept-Language |
string |
Language code. Default: Company defined default language |
hasChildren |
boolean |
If true, displays items with children. |
isDeleted |
boolean |
If true, displays deleted items. |
listId |
string |
Required The unique identifier of the list. |
page |
integer |
Page number starting from 1. Default: 1 |
shortCode |
string |
Filter capabilities for shortCode. |
shortCodeOrValue |
string |
Filter capabilities for value or shortCode. |
sortBy |
string |
Field to sort by. Supported values: value, shortCode. Default: value |
sortDirection |
string |
Sort direction. Supported values: asc, desc |
value |
string |
Filter capabilities for value. |
Headers
Response
Status Codes
Headers
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7230 Content-Length
- RFC 7231 Content-Type
- RFC 7231 Date
- RFC 7232 ETag
- RFC 7234 Cache-Control
Payload
Example
Request
GET https://us.api.concursolutions.com/list/v4/lists/7c6d0435-c4d1-8b48-8492-7e7b625e148d/children?page=1&sortBy=value
Accept: application/json
Accept-Language: en
Authorization: Bearer {token}
Response
HTTP/1.1 200
concur-correlationid: 50dcec14-c984-479c-84e2-186a7e62f87e
content-length: 449
content-type: application/json;charset=UTF-8
date: Wed, 08 Jul 2020 14:27:13 GMT
etag: "05cb0f0ed5a73bedf1e8cd4171e360e41"
cache-control: no-cache, private
{
"links": [],
"content": [
{
"id": "63b7fbd9-ae08-0840-abdb-62b0b9160081",
"code": "ITEM-FIRST LEVEL ITEM",
"shortCode": "FIRST LEVEL ITEM",
"value": "FIRST LEVEL ITEM",
"level": 1,
"isDeleted": false,
"lists": [
{
"id": "7c6d0435-c4d1-8b48-8492-7e7b625e148d",
"hasChildren": false
}
]
}
],
"page": {
"size": 100,
"totalElements": 1,
"totalPages": 1,
"number": 1
}
}
Filtering
Supported APIs
The List Item API supports filtering on the Retrieve First Level Children Items of a List,
Retrieve Children of a List Item, and Retrieve Children of a List Item by List APIs.
The filter may be applied to the value, shortCode, and shortCodeOrValue query parameters.
Retrieve First Level Children Items of a List
GET /lists/v4/lists/{listId}/children?value=test
GET /lists/v4/lists/{listId}/children?shortCode=test
GET /lists/v4/lists/{listId}/children?shortCodeOrValue=test
Retrieve Children of a List Item
GET /lists/v4/items/{listId}/children?value=test
GET /lists/v4/items/{listId}/children?shortCode=test
GET /lists/v4/items/{listId}/children?shortCodeOrValue=test
Retrieve Children of a List Item by List
GET /list/v4/lists/{listId}/items/{itemId}/children?value=test
GET /list/v4/lists/{listId}/items/{itemId}/children?shortCode=test
GET /list/v4/lists/{listId}/items/{itemId}/children?shortCodeOrValue=test
Query Syntax
The general format of a query syntax parameter is as follows:
/lists/v4/resource?field_name=<op>:<value>
field_name- The name of the field that will be compared against.op- (Optional) The comparison operator to use when comparing the specified value to the field. Defaults toeq.value- The value being checked for.
Ensure the url generated is properly URL encoded. For example, if you have a field_name or value with a &, please convert it to %26.
Examples:
/lists/v4/lists/{listId}/children?value=PSO
/lists/v4/lists/{listId}/children?shortCode=sw:British
/lists/v4/lists/{listId}/children?value=ew:Airlines&shortCode=not:British+Airlines
/lists/v4/lists/{listId}/children?value=sw:Question%3FMark
Conjunction Operators
Complex queries using parentheses are not supported.
There is basic support for OR functionality with the shortCodeOrValue query parameter. shortCodeOrValue will search both shortCode and value properties and return all resources that match either field.
Comparison Operators
Equals
eq returns results where a field is equal to the supplied value. This is the default if no operator is specified.
/lists/v4/lists/{listId}/children?value=test
/lists/v4/items/{itemId}/children?value=eq:test
/lists/v4/items/{itemId}/children?shortCodeOrValue=eq:test
Contains Pattern
cp returns results where the provided pattern exists in the specified field.
/lists/v4/lists/{listId}/children?value=cp:test
Not
not returns results where a field is not equal to the supplied value.
/lists/v4/items/{itemId}/children?shortCode=not:test
Starts With
sw returns results where a field startsWith the supplied value.
/lists/v4/lists/{listId}/children?shortCode=sw:test
Ends With
ew returns results where a field endsWith the supplied value.
/lists/v4/items/{itemId}/children?value=ew:test
Schema
List Item
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
uuid |
The unique identifier of the list item. |
code |
string |
- | List item long code. |
shortCode |
string |
- | List item short code. |
value |
string |
- | List item value. |
parentId |
string |
uuid |
The unique identifier of the parent list item. |
listId |
string |
uuid |
The unique identifier of the list that contains the list item. |
level |
integer |
int32 |
Level of the list item within the list. |
lists |
ListItemMemberList |
- | The unique identifiers of the lists that contains the list item. The list item may exist under one or more lists. |
isDeleted |
boolean |
true/false |
Indicates the deleted state of the item in a particular list. If false, the list item is not deleted from one or more lists. The lists field will include only the lists that contain the list item in a not-deleted state. isDeleted will only be true when the list item is deleted from all lists. The lists field will include all lists that contain the list item. |
List Item Create
| Name | Type | Format | Description |
|---|---|---|---|
listId |
string |
uuid |
Required The unique identifier of the list that contains the list item. |
parentCode |
string |
- | The long code of parent list item. |
parentId |
string |
uuid |
The unique identifier of parent list item. |
shortCode |
string |
- | Required List item short code. |
value |
string |
- | Required List item value. |
List Item Update
| Name | Type | Format | Description |
|---|---|---|---|
shortCode |
string |
- | Required List item short code. |
value |
string |
- | Required List item value. |
List Item Member List
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
uuid |
The unique identifier of the list that contains the list item. |
hasChildren |
boolean |
true/false |
If true, the list item has children in this particular list. |
Paged Resources List Item
| Name | Type | Format | Description |
|---|---|---|---|
content |
array |
ListItem |
- |
page |
PageMetadata |
- | Metadata for the page of data returned |
links |
array |
Link |
Href links to the next, previous, first, and/or last pages of data. |
Error Message
| Name | Type | Format | Description |
|---|---|---|---|
error |
Message |
- | Required The detailed error message. |
httpStatus |
string |
- | Required The http response code and phrase for the response. |
path |
string |
- | Required The URI of the attempted request. |
timestamp |
string |
date-time |
Required The time when the error was captured. |
validationErrors |
array |
ValidationError |
The validation error messages. |
Validation Error
| Name | Type | Format | Description |
|---|---|---|---|
message |
string |
- | The detailed message of the validation error. |
source |
string |
- | The type of validation that failed. |
Message
| Name | Type | Format | Description |
|---|---|---|---|
message |
string |
- | The detailed error message. |
id |
string |
- | The identifier of the error. |
Page Metadata
| Name | Type | Format | Description |
|---|---|---|---|
number |
integer |
int32 |
The page number. |
size |
integer |
int32 |
The number of items per page, which is fixed at 100. |
totalElements |
integer |
int32 |
The number of total elements. |
totalPages |
integer |
int32 |
The number of total pages. |
Link
| Name | Type | Format | Description |
|---|---|---|---|
rel |
string |
- | The link relation. |
href |
string |
- | The link href. |
Lists v3
This API has been deprecated.
Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.
Learn more in the API Lifecycle & Deprecation Policy.
The Lists API allows you to view your configured lists within SAP Concur products, and create new lists. The lists are shared between multiple SAP Concur products. Use the List Items API to manage the items in the lists.
- Products and Editions
- Scope Usage
- Get All Lists
- Create a New List
- Get a Single List by ID
- Update List Deprecated
- Schema
Products and Editions
- Concur Expense Professional Edition
- Concur Expense Standard Edition
- Concur Invoice Professional Edition
- Concur Invoice Standard Edition
- Concur Request Professional Edition
- Concur Request Standard Edition
Scope Usage
| Name | Description | Endpoint |
|---|---|---|
LIST |
Use and update lists configured by your company. | GET, POST |
Get All Lists
Returns all lists based on the search criteria.
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
limit |
integer |
The default is 25 and the maximum is 100. | Optional. The number of records to return. |
offset |
string |
- | Optional. The start of the page offset. The default is from the beginning. |
Request
GET https://www.concursolutions.com/api/v3.0/common/lists HTTP/1.1
Host: www.concursolutions.com
Accept: application/json
const headers = {
'Accept':'application/json'
};
fetch('https://www.concursolutions.com/api/v3.0/common/lists',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
Response
200 Response
{
"Items": {
"ConnectorID": "string",
"DisplayCodeFirst": true,
"ExternalThreshold": 0,
"ID": "string",
"IsVendorList": true,
"Name": "string",
"SearchCriteriaCode": "string",
"URI": "string"
},
"NextPage": "string"
}
Create a New List
Creates a new list.
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
content |
ListPost | - | Required. List object to create. |
Request
POST https://www.concursolutions.com/api/v3.0/common/lists HTTP/1.1
Host: www.concursolutions.com
Content-Type: application/json
Accept: application/json
const inputBody = '{
"ConnectorID": "string",
"DisplayCodeFirst": true,
"ExternalThreshold": 0,
"IsVendorList": true,
"Name": "string",
"SearchCriteriaCode": "string"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json'
};
fetch('https://www.concursolutions.com/api/v3.0/common/lists',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
Response
200 Response
{
"ID": "string",
"URI": "string"
}
Get a Single List by ID
Returns a list by ID.
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
- | Required.The unique identifier for the list. |
Request
GET https://www.concursolutions.com/api/v3.0/common/lists/{id} HTTP/1.1
Host: www.concursolutions.com
Accept: application/json
const headers = {
'Accept':'application/json'
};
fetch('https://www.concursolutions.com/api/v3.0/common/lists/{id}',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
Response
200 Response
{
"ConnectorID": "string",
"DisplayCodeFirst": true,
"ExternalThreshold": 0,
"ID": "string",
"IsVendorList": true,
"Name": "string",
"SearchCriteriaCode": "string",
"URI": "string"
}
Update List
DEPRECATED: 05/19/2016 UNSUPPORTED: 11/19/2016. Updates list specified in the URL. Only the fields provided in the supplied object will be updated, missing fields will not be altered.
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
- | Required. The unique identifier for the list. |
content |
ListPut | - | Required. The list object to update. |
Request
PUT https://www.concursolutions.com/api/v3.0/common/lists/{id} HTTP/1.1
Host: www.concursolutions.com
Content-Type: application/json
Accept: application/json
const inputBody = '{
"DisplayCodeFirst": true,
"Name": "string",
"SearchCriteriaCode": "string"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json'
};
fetch('https://www.concursolutions.com/api/v3.0/common/lists/{id}',
{
method: 'PUT',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
Schema
CreateResponse
| Name | Type | Format | Description |
|---|---|---|---|
ID |
string |
- | |
URI |
string |
- |
ListGet
| Name | Type | Format | Description |
|---|---|---|---|
ConnectorID |
string |
- | Optional. Defines the encrypted ConnectorID. If not provided then the list isn't associated with a connector. |
DisplayCodeFirst |
Boolean |
- | Required. Defines whether code should appear before text, or vice versa. |
ExternalThreshold |
integer |
- | Optional. Default value is 1. Defines the threshold from where the level starts being external. This value can only be set if a ConnectorID is provided. |
ID |
string |
- | The unique identifier of the resource. |
IsVendorList |
Boolean |
- | Required. Defines whether it is a vendor list. |
Name |
string |
- | Required. Defines a name for the list. This name must be unique. |
SearchCriteriaCode |
string |
- | Required. Defines whether the search criteria should apply to the code or to the text. |
URI |
string |
- | The URI to the resource. |
ListGetCollection
| Name | Type | Format | Description |
|---|---|---|---|
Items |
ListGet | - | |
NextPage |
string |
- | The URI of the next page of results, if any. |
ListPost
| Name | Type | Format | Description |
|---|---|---|---|
ConnectorID |
string |
- | Optional. Defines the encrypted ConnectorID. If not provided then the list isn't associated with a connector. |
DisplayCodeFirst |
Boolean |
- | Required. Defines whether code should appear before text, or vice versa. |
ExternalThreshold |
integer |
- | Optional. Default value is 1. Defines the threshold from where the level starts being external. This value can only be set if a ConnectorID is provided. |
IsVendorList |
Boolean |
- | Required. Defines whether it is a vendor list. |
Name |
string |
- | Required. Defines a name for the list. This name must be unique. |
SearchCriteriaCode |
string |
- | Required. Defines whether the search criteria should apply to the code or to the text. |
ListPut
| Name | Type | Format | Description |
|---|---|---|---|
DisplayCodeFirst |
Boolean |
- | Optional. Defines whether code should appear before text, or vice versa. |
Name |
string |
- | Optional. Defines a name for the list. This name must be unique. |
SearchCriteriaCode |
string |
- | Optional. Defines whether the search criteria should apply to the code or to the text. |
List v4
The Lists APIs allow you to view your configured lists within SAP Concur products and create new lists. The lists are shared between multiple SAP Concur products.
Limitations: This API is only available to partners who have been granted access by SAP Concur. Access to this documentation does not provide access to the API.
Contents
- Process Flow
- Products and Editions
- Scope Usage
- Dependencies
- Access Token Usage
- Get All Lists
- Create a New List
- Update a List
- Get a List by List ID
- Get a List by Category ID
- Remove a List
- Schema
Prior Versions
List v3 documentation is available here.
Process Flow

Products and Editions
- Concur Expense Professional Edition
- Concur Expense Standard Edition
- Concur Invoice Professional Edition
- Concur Invoice Standard Edition
- Concur Request Professional Edition
- Concur Request Standard Edition
Scope Usage
| Name | Description | Endpoints |
|---|---|---|
spend.list.read |
Read-only access to spend lists. | GET |
spend.list.write |
Read and write access to spend lists. | GET, POST, PUT |
spend.list.delete |
Delete capabilities for spend lists. | DELETE |
Dependencies
Users must be an Expense, Invoice, Shared or Request Configuration Administrator in order to perform POST, PUT, and DELETE actions.
Access Token Usage
This API supports both company level and user level access tokens.
Get All Lists
Returns all lists for a company.
Scopes
spend.list.read - Refer to Scope Usage for full details.
Request
URI
Template
GET /list/v4/lists
Parameters
| Name | Type | Description |
|---|---|---|
Accept-Language |
string |
Language code. Default: Company defined default language |
page |
integer($int32) |
Page number starting from 1. Default: 1 |
sortBy |
string |
Field to order by {name, levelcount, listcategory}. Sort by name is ordered by value. Sort by levelcount is ordered by levelCount. Sort by listcategory is ordered by category.type. Default: name |
sortDirection |
string |
Sort direction {asc, desc}. Default: asc |
Headers
Response
Status Codes
- 200 OK
- 400 Bad Request - Company does not exist
- 401 Unauthorized - Access Denied
- 500 Internal Server Error
Headers
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7230 Content-Length
- RFC 7231 Content-Type
- RFC 7231 Date
- RFC 7232 ETag
- RFC 7234 Cache-Control
Payload
Example
Request
GET https://us.api.concursolutions.com/list/v4/lists?page=1
Accept: application/json
Accept-Language: en
Authorization: Bearer {token}
Response
HTTP/1.1 200
concur-correlationid: 746696dc-8782-4642-815d-3080640786c7
content-length: 5632
content-type: application/json;charset=UTF-8
date: Wed, 08 Jul 2020 02:45:48 GMT
etag: "02ebe9fc5c950a031f85c57ac91a0babb"
cache-control: no-cache, private
{
"links": [],
"content": [
{
"id": "a80a5070-3951-4316-886a-a60ab790f06b",
"value": "Airlines",
"levelCount": 1,
"searchCriteria": "TEXT",
"displayFormat": "(CODE) TEXT",
"category": {
"id": "a2dfc451-8f3c-410e-a5f2-20d79c8fc3dc",
"type": "Vendor"
},
"isReadOnly": false,
"isDeleted": false
},
{
"id": "8652cdf9-c12b-4051-b8d1-80e20840ce9b",
"value": "Employee Groups",
"levelCount": 1,
"searchCriteria": "TEXT",
"displayFormat": "(CODE) TEXT",
"category": {
"id": "d232b1e3-43da-4a2d-adaf-eb948045e8cf",
"type": "Configuration"
},
"isReadOnly": false,
"isDeleted": false
}
],
"page": {
"size": 100,
"totalElements": 2,
"totalPages": 1,
"number": 1
}
}
Create a New List
Creates a new list.
Scopes
spend.list.write - Refer to Scope Usage for full details.
Request
URI
Template
POST /list/v4/lists
Parameters
| Name | Type | Description |
|---|---|---|
Accept-Language |
string |
Language code. Default: Company defined default language |
listRequest |
- | Required List object that is created for the company. |
Headers
Payload
Response
Status Codes
- 201 Created
- 400 Bad Request - Company does not exist
- 401 Unauthorized
- 403 Forbidden
- 415 Unsupported Media Type
- 500 Internal Server Error
Headers
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7230 Content-Length
- RFC 7231 Content-Type
- RFC 7231 Date
- RFC 7231 Location
- RFC 7234 Cache-Control
Payload
Example
Request
POST https://us.api.concursolutions.com/list/v4/lists
Accept: application/json
Content-Type: application/json
Authorization: Bearer {token}
Example 1:
{
"searchCriteria": "TEXT",
"value": "Custom List",
"displayFormat": "(CODE) TEXT"
}
Example 2:
{
"searchCriteria": "TEXT",
"value": "Custom Vendor List",
"categoryId": "a2dfc451-8f3c-410e-a5f2-20d79c8fc3dc",
"displayFormat": "(CODE) TEXT"
}
Response
HTTP/1.1 201
concur-correlationid: 5512c7be-3fab-4d65-ae69-8a74a04a0c7f
content-length: 269
content-type: application/json;charset=UTF-8
date: Wed, 08 Jul 2020 03:00:42 GMT
location: http://us.api.concursolutions.com/list/v4/lists/80edb3fa-c15e-a34a-b97f-f2ec291ab44f
cache-control: no-cache, private
{
"id": "80edb3fa-c15e-a34a-b97f-f2ec291ab44f",
"value": "Custom List",
"levelCount": 1,
"searchCriteria": "TEXT",
"displayFormat": "(CODE) TEXT",
"category": {
"id": "77b85a76-8157-0c4e-b5e3-7785d8de1a6b",
"type": "Normal"
},
"isReadOnly": false,
"isDeleted": false
}
Update a List
Update an existing list.
Scopes
spend.list.write - Refer to Scope Usage for full details.
Request
URI
Template
PUT /list/v4/lists/{listId}
Parameters
| Name | Type | Description |
|---|---|---|
Accept-Language |
string |
Language code. Default: Company defined default language |
listId |
string($uuid) |
Required The unique identifier of the list. |
listUpdate |
- | Required List object that is updated for the company. |
Headers
Payload
Response
Status Codes
- 200 OK
- 400 Bad Request - Company does not exist
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found - List not found
- 415 Unsupported Media Type
- 500 Internal Server Error
Headers
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7230 Content-Length
- RFC 7231 Content-Type
- RFC 7231 Date
- RFC 7234 Cache-Control
Payload
Example
Request
PUT https://us.api.concursolutions.com/list/v4/lists/80edb3fa-c15e-a34a-b97f-f2ec291ab44f
Accept: application/json
Accept-Language: en
Content-Type: application/json
Authorization: Bearer {token}
{
"value": "Custom List Renamed",
"searchCriteria": "TEXT",
"displayFormat": "(CODE) TEXT"
}
Response
HTTP/1.1 200
concur-correlationid: e3a4d4cf-e1b2-4f22-a95c-b5bb8a2cb0e1
content-length: 275
content-type: application/json;charset=UTF-8
date: Wed, 08 Jul 2020 03:24:16 GMT
cache-control: no-cache, private
{
"id": "80edb3fa-c15e-a34a-b97f-f2ec291ab44f",
"value": "Custom List Renamed",
"levelCount": 1,
"searchCriteria": "TEXT",
"displayFormat": "(CODE) TEXT",
"category": {
"id": "77b85a76-8157-0c4e-b5e3-7785d8de1a6b",
"type": "Normal"
},
"isReadOnly": false,
"isDeleted": false
}
Get a List by List ID
Returns a list by a List ID.
Scopes
spend.list.read - Refer to Scope Usage for full details.
Request
URI
Template
GET /list/v4/lists/{listId}
Parameters
| Name | Type | Description |
|---|---|---|
Accept-Language |
string |
Language code. Default: Company defined default language |
listId |
string($uuid) |
Required The unique identifier of the list. |
Headers
Response
Status Codes
- 200 OK
- 400 Bad Request - Company does not exist
- 401 Unauthorized
- 404 Not Found
- 500 Internal Server Error
Headers
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7230 Content-Length
- RFC 7231 Content-Type
- RFC 7231 Date
- RFC 7232 ETag
- RFC 7234 Cache-Control
Payload
Example
Request
GET https://us.api.concursolutions.com/list/v4/lists/80edb3fa-c15e-a34a-b97f-f2ec291ab44f
Accept: application/json
Accept-Language: en
Authorization: Bearer {token}
Response
HTTP/1.1 200
concur-correlationid: 6a5803f6-b63b-49d8-88b3-872f456206c2
content-length: 275
content-type: application/json;charset=UTF-8
date: Wed, 08 Jul 2020 02:45:48 GMT
etag: "08514b0fce90d634c211aba29d1cc94c2"
cache-control: no-cache, private
{
"id": "80edb3fa-c15e-a34a-b97f-f2ec291ab44f",
"value": "Custom List Renamed",
"levelCount": 1,
"searchCriteria": "TEXT",
"displayFormat": "(CODE) TEXT",
"category": {
"id": "77b85a76-8157-0c4e-b5e3-7785d8de1a6b",
"type": "Normal"
},
"isReadOnly": false,
"isDeleted": false
}
Get a List by Category ID
Returns a list by a category ID.
Scopes
spend.list.read - Refer to Scope Usage for full details.
Request
URI
Template
GET /list/v4/categories/{categoryId}/lists
Parameters
| Name | Type | Description |
|---|---|---|
Accept-Language |
string |
Language code. Default: Company defined default language |
categoryId |
string($uuid) |
Required The unique identifier of the category. |
page |
integer($int32) |
Page number starting from 1. Default: 1 |
Headers
- RFC 7231 Accept
- RFC 7231 Accept-Language
- RFC 7231 Content-Type
- RFC 7232 If-None-Match
- RFC 7235 Authorization
Response
Status Codes
- 200 OK
- 400 Bad Request - Company does not exist
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found - List category not found
- 415 Unsupported Media Type
- 500 Internal Server Error
Headers
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7230 Content-Length
- RFC 7231 Content-Type
- RFC 7231 Date
- RFC 7232 ETag
- RFC 7234 Cache-Control
Payload
Example
Request
GET https://us.api.concursolutions.com/list/v4/categories/77b85a76-8157-0c4e-b5e3-7785d8de1a6b/lists?page=1
Accept: application/json
Accept-Language: en
Authorization: Bearer {token}
Response
HTTP/1.1 200
concur-correlationid: 0e80dff7-93b7-4b43-a1b6-a91ebe5c55f0
content-length: 364
content-type: application/json;charset=UTF-8
date: Wed, 08 Jul 2020 02:45:48 GMT
etag: "02e60234cf6ae61aadd7f066e839b07fb"
cache-control: no-cache, private
{
"links": [],
"content": [
{
"id": "80edb3fa-c15e-a34a-b97f-f2ec291ab44f",
"value": "Custom List Renamed",
"levelCount": 1,
"searchCriteria": "TEXT",
"displayFormat": "(CODE) TEXT",
"category": {
"id": "77b85a76-8157-0c4e-b5e3-7785d8de1a6b",
"type": "Normal"
},
"isReadOnly": false,
"isDeleted": false
}
],
"page": {
"size": 100,
"totalElements": 1,
"totalPages": 1,
"number": 1
}
}
Remove a List
Delete a list.
Scopes
spend.list.delete - Refer to Scope Usage for full details.
Request
URI
Template
DELETE /list/v4/lists/{listId}
Parameters
| Name | Type | Description |
|---|---|---|
listId |
string($uuid) |
Required The unique identifier of the list. |
Headers
Response
Status Codes
- 204 No Content - List resource no longer in system
- 400 Bad Request - List could not be deleted
- 401 Unauthorized
- 403 Forbidden
- 500 Internal Server Error
Headers
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7231 Date
- RFC 7234 Cache-Control
Payload
Example
Request
DELETE https://us.api.concursolutions.com/list/v4/lists/80edb3fa-c15e-a34a-b97f-f2ec291ab44f
Accept: application/json
Authorization: Bearer {token}
Response
HTTP/1.1 204
concur-correlationid: d92ab0c7-510b-4730-99a8-14a79ad99b7c
date: Wed, 08 Jul 2020 02:45:48 GMT
cache-control: no-cache, private
Schema
Paged Resources List Response
| Name | Type | Format | Description |
|---|---|---|---|
content |
array |
ListResponse |
- |
page |
PageMetadata |
- | Metadata for the page of data returned. |
links |
array |
Link |
Href links to the next, previous, first, and/or last pages of data. |
List Response
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
uuid |
Unique identifier of a list. |
value |
string |
- | Name of the list. |
levelCount |
integer |
int32 |
Number of levels in the list. |
searchCriteria |
string |
- | What attribute to search by {TEXT, CODE}. |
displayFormat |
string |
- | Whether the code or value is displayed first {(CODE) TEXT, TEXT (CODE)}. |
category |
ListCategory |
- | The category of the list. |
isReadOnly |
boolean |
true/false |
If true, the list is read-only. |
isDeleted |
boolean |
true/false |
If true, the list has been deleted. |
List Category
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
uuid |
Unique identifier of a category. |
type |
string |
- | Category type. |
List Request
| Name | Type | Format | Description |
|---|---|---|---|
searchCriteria |
string |
- | What attribute to search by. Supported values: TEXT, CODE |
value |
string |
- | Required Name of the list. |
categoryId |
string |
uuid |
The unique identifier of the category that the list belongs to. |
displayFormat |
string |
- | Whether we display code or value first. Supported values: (CODE) TEXT, TEXT (CODE) |
List Update
| Name | Type | Format | Description |
|---|---|---|---|
value |
string |
- | Required Name of the list. |
searchCriteria |
string |
- | What attribute to search by. Supported values: TEXT, CODE |
displayFormat |
string |
- | Whether we display code or value first. Supported values: (CODE) TEXT, TEXT (CODE) |
Message
| Name | Type | Format | Description |
|---|---|---|---|
message |
string |
- | The detailed error message. |
id |
string |
- | The identifier of the error. |
Page Metadata
| Name | Type | Format | Description |
|---|---|---|---|
number |
integer |
int32 |
The page number. |
size |
integer |
int32 |
The number of lists per page, which is fixed at 100. |
totalElements |
integer |
int32 |
The number of total elements. |
totalPages |
integer |
int32 |
The number of total pages. |
Link
| Name | Type | Format | Description |
|---|---|---|---|
rel |
string |
- | The link relation. |
href |
string |
- | The link href. |
Error Message
| Name | Type | Format | Description |
|---|---|---|---|
error |
Message |
- | Required The detailed error message. |
httpStatus |
string |
- | Required The http response code and phrase for the response. |
path |
string |
- | Required The URI of the attempted request. |
timestamp |
string |
date-time |
Required The time when the error was captured. |
validationErrors |
array |
ValidationError |
The validation error messages. |
Validation Error
| Name | Type | Format | Description |
|---|---|---|---|
message |
string |
- | The detailed message of the validation error. |
source |
string |
- | The type of validation that failed. |
Locations v3
Gets details of locations that are used by Concur and that are valid at the user's company.
- Retrieve details of locations that are used by Concur and that are valid at the user's company
- Retrieve details of a specified location
- Schema
Location v1.1 has been deprecated and can be found here.
Retrieve details of locations that are used by Concur and that are valid at the user's company
GET /api/v3.0/common/locations
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
offset |
string |
query |
The starting point of the next set of results, after the limit specified in the limit field has been reached. |
limit |
Int32 |
query |
The number of records to return. Default value: 25 |
name |
string |
query |
A common name associated with the location. This name can be a location description such as a neighborhood (SoHo), a landmark (Statue of Liberty), or a city name (New York). |
city |
string |
query |
The city name of the location. |
countrySubdivision |
string |
query |
The ISO 3166-2:2007 country subdivision code for the location. Example: US-WA |
country |
string |
query |
The 2-letter ISO 3166-1 country code for the location. Example: United States is US |
administrativeRegion |
string |
query |
The administrative region of the location. An administrative region is a government unit, such as a county, that contains one or more cities. |
Retrieve details of a specified location
GET /api/v3.0/common/locations/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required The ID of the location. |
Schema
Locations
| Name | Type | Format | Description |
|---|---|---|---|
Items |
Array |
Location | The result collection. |
NextPage |
string |
- | The URI of the next page of results, if any. |
Location
| Name | Type | Format | Description |
|---|---|---|---|
AdministrativeRegion |
string |
- | The administrative region of the location. |
Country |
string |
- | The 2-letter ISO 3166-1 country code for the location. |
CountrySubdivision |
string |
- | The ISO 3166-2:2007 country subdivision code for the location. Example: US-WA |
IATACode |
string |
- | The International Air Transport Association (IATA) airport code of the location. |
ID |
string |
- | The unique identifier of the resource. |
IsAirport |
boolean |
- | Indicates whether the location is an airport. Format: true or false |
IsBookingTool |
boolean |
- | Indicates whether the location is used by the booking tool. Format: true or false |
Latitude |
Decimal |
- | The latitude of the geocode for the location. |
Longitude |
Decimal |
- | The longitude of the geocode for the location. |
Name |
string |
- | The location name. Maximum length: 64 characters |
URI |
string |
- | The URI to the resource. |
Suppliers v3
Suppliers
Supplier companies provide travel services to users. The Suppliers resource can be used to retrieve information about suppliers.
Retrieve all suppliers based on search criteria
GET /api/v3.0/common/suppliers/
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
name |
query |
string |
Name |
address |
query |
string |
Address |
address2 |
query |
string |
Address |
city |
query |
string |
City |
state |
query |
string |
State |
zip |
query |
string |
Zip |
country |
query |
string |
Country Code |
phone |
query |
string |
Phone |
mcCode |
query |
string |
MCC Code (Ex: Delta Airline - 3058) |
taxId |
query |
string |
Tax Id |
merchantType |
query |
string |
Merchant Type Code(Ex: Visa - VI, Amex - AX) |
merchantID |
query |
string |
Merchant Id |
iataCode |
query |
string |
IATA Code |
relevance |
query |
Int32 |
Relevance of the Search results5 |
Retrieve a single supplier by ID
GET /api/v3.0/common/suppliers/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required Supplier ID. |
Schema
Suppliers
| Name | Type | Format | Description |
|---|---|---|---|
Items |
Array |
Supplier | The result connection |
NextPage |
string |
- | The URI of the next page of results, if any. |
Supplier
| Name | Type | Format | Description |
|---|---|---|---|
AmadeusId |
string |
- | Amadeus Id |
AustinTetra |
string |
- | Austin Tetra |
BusinessName |
string |
- | Name |
ChainCode |
string |
- | Chain Code |
ChainName |
string |
- | Chain Name |
City |
string |
- | City |
CountryCode |
string |
- | Country Code |
CreditCardVendorId |
string |
- | Creditcard Vendor Id |
DunsNumber |
string |
- | Duns Number |
Email |
string |
- | |
Fax |
string |
- | Fax |
GalileoId |
string |
- | Galileo Id |
ID |
string |
- | The unique identifier of the resource. |
MccCode |
string |
- | MCC Code (Ex: Delta Airline - 3058) |
NorthstarId |
string |
- | Northstar Id |
PegasusId |
string |
- | Pegasus Id |
Phone |
string |
- | Phone |
PostalCode |
string |
- | Zip |
PrimaryNaics |
string |
- | Primary Naics Code |
PrimarySic |
string |
- | Primary Sic Code |
PropertyCode |
string |
- | SUP_PARAM_PROPERTY_CODE |
SabreId |
string |
- | Sabre Id |
SecondaryNaics |
string |
- | Secondary Naics Code |
SecondarySic |
string |
- | Secondary Sic Code |
State |
string |
- | State |
StreetAddress |
string |
- | Address |
StreetAddress2 |
string |
- | Address2 |
TaxId |
string |
- | Tax Id |
TollFree |
string |
- | Toll Free |
URI |
string |
- | The URI to the resource. |
WebUrl |
string |
- | Web Address |
WorldspanId |
string |
- | Worldspan Id |
DETOKENIZER
Detokenizer v4
Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.
The Detokenizer service allows clients to retrieve the user's credit card number from Concur Expense in a secure way. The Detokenizer service returns the user's credit card number encrypted with a public key that the client provides in the request. The client will be able to decrypt the user's credit card number using their private key.
Limitations: This API is only for internal use to support various SAP integration features or to the SAP Concur customer that has established corporate credit card accounts involved in the data (the “Customer Corporate Card Holder”). Such use must be in compliance with regulations and other industry standards, including but not limited to Payment Card Industry Data Security Standards (PCI DSS). If you are a Customer Corporate Card Holder that desires to use this API, you must work with your account manager to establish use rights. Please be aware that if such rights are established, you will be responsible for compliance according to the terms of your customer agreement. No other third parties may use this API without explicit approval from SAP Legal. Access to this documentation does not provide access to the API.
Contents
- Products and Editions
- Scope Usage
- Dependencies
- Access Token Usage
- Get Credit Card Account Details
- Schema
Products and Editions
- Concur Expense Professional Edition
Scope Usage
| Name | Description | Endpoint |
|---|---|---|
creditcardaccountnumber.read or creditcardaccount.read |
Reads credit card data from Concur Expense. | GET |
Dependencies
SAP Concur clients must purchase Concur Expense in order to use this API.
The user may use the following SAP Concur APIs to get additional information: * Profile v1 - Company
Access Token Usage
This API supports company level access tokens.
Get Credit Card Account Details
Returns the credit card number encrypted with the public key provided in the request.
Scopes
creditcardaccountnumber.read or creditcardaccount.read - Refer to Scope Usage for full details.
Request
GET https://{region}.api.concursolutions.com/detokenizer/v4/company/{companyUUID}/creditcard/{creditcardGUID}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
pubkeyAlgorithm |
string |
- | The RSA algorithm used by the PublicKey for credit card number encryption. |
pubkeyFormat |
string |
- | Public key format. |
pubkey |
string |
- | Public key. |
companyUUID |
string |
- | Company UUID. |
creditcardGUID |
string |
- | Credit card GUID. |
Headers
- RFC 7235 Authorization : Header used for authorization. Should be specified in the format 'Bearer JWT_Token'. This is a Company JWT token.
Payload
- None.
Response
Status Codes
Headers
concur-correlationidis an SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7231 Content-Type
- RFC 7230 Content-Length
Payload
Example
Request
GET https://us.api.concursolutions.com/detokenizer/v4/company/d295261b-e624-442b-b771-9c7f00c1ed9a/creditcard/BB98EABE1DDA7B48B858CFDC7EEE2A10?pubkeyAlgorithm=rsa_pkcs7&pubkeyFormat=cert&pubkey=PUBLIC_KEY
Authorization: Bearer JWT_TOKEN
Accept: application/json
Response
HTTP/1.1 200 OK
concur-correlationid: 87de8598-dbd5-4aea-af9d-988efb61c468
Content-Type: application/json
Content-Length: 1270
{
"accountNumber": "MIAGCSqGSIb3DQEHA6CAMIACAQAxgbUwgbICAQAwGzAPMQ0wCwYDVQQDDARUZXN0AghyaD1Uj9uSsDANBgkqhkiG9w0BAQEFAASBgAk0/9Yd5CQt5/6vQ1gO9aSivBJrv4AOAluZ876tqVI+fCZi7P1YojC4nTkvl358zfD3vXE3ehj14FfIPZlwmuVlSZF4ad5ni2B78fs5Jr6lxhG9iPU0FyFv+NhuIet/mpEaaX2CWB8CUwkTVdDyT5UjrwqsvYpRCwLz0Hx76BO8MIAGCSqGSIb3DQEHATAdBglghkgBZQMEAQIEEPo3PO3VplgQ4mN0L5KInPKggAQgkqu7zWslGq3uqw0G2WXkK0QA2p0YHQuwhEPT2JMF5mUAAAAAAAAAA"
}
Schema
Account Number
| Name | Type | Format | Description |
|---|---|---|---|
accountNumber |
string |
- | Encrypted credit card account number. |
GROUND-TRANSPORTATION
Direct Connect - Ground Transportation
The Ground Transportation Direct Connect provides a method for Travel users to access the inventory of ground transportation service providers. This direct connect was originally designed for use by limo service providers, but can be used with all forms of ground transportation.
Once the ground transportation supplier has developed their interface with SAP Concur, their inventory will begin appearing in ground transportation searches by opted-in Travel users.
This callout differs from the inbound SAP Concur web services in the following ways:
- It uses an outbound message where Travel calls a public facing API endpoint provided by the ground transportation supplier.
- The supplier configures and maintains the public web service interface. This guide specifies the request and response format required by SAP Concur.
NOTE: This direct connect was originally designed to work with Limo providers, but can support all types of ground transportation.
- Products and Editions
- Product Restrictions
- Configuration Process
- Authentication
- Operations
- GDS Sell Formats
Products and Editions
- Concur Travel Professional Edition
- Concur Travel Standard Edition
Product Restrictions
This direct connect is only available to Travel Suppliers with Ground Transportation inventory. This direct connect is not supported in the SAP Concur mobile application.
SAP Concur products are highly configurable, and not all clients will have access to all features.
Partner developers must determine which configurations are required for their solution prior to the review process.
Configuration Process
The configuration process has the following steps:
- The Travel Supplier creates the application on their system that will accept the requests from SAP Concur and return the appropriate responses.
- The Travel Supplier creates the endpoint on their system that SAP Concur uses to access their inventory.
- SAP Concur creates a production company for the travel supplier.
- The Travel Supplier registers their application with SAP Concur by logging in to their production company.
- SAP Concur configures Travel to send requests to the endpoint.
- The Travel client opts in to the Ground Transportation callout using the Travel Configuration UI to allow their users to view and book the available inventory. Clients must contact SAP Concur to have this setting activated
Once the configuration is complete, the callout uses the following process:
- The user searches for ground transportation when creating an itinerary in Travel.
- Travel sends the search details to the endpoint, using the Post Search Request.
- The supplier returns the search results.
- If the user chooses to reserve the ride, Travel sends the Post Sell Request.
- The supplier returns the Post Sell Reply.
This callout can also be used to perform the following operations:
- Get the Reservation Details
- Cancel the Ground Transportation Reservation
- Update the Ground Transportation Reservation with the Supplier
Authentication
Authentication between SAP Concur and the application connector is performed using OAuth.
Operations
Post Reservation Detail Search
Update Reservation with the Supplier
GDS Sell Formats
Sabre:
1 OTH LM 14MAY M GK1 DCA/PCI QA TEST/TEL 201 555 1212/RATE-$0.00/CONF-/PICKUP-209 MADISON ST SUITE 400 ALEXANDRIAVA 22314 AT 0900/DROPOFF-DCA AIRPORT AT 0915/203121365/RESERVATION L1
Apollo:
1 LIM ZM GK1 DCA 09MAY-/PCI QA TEST-TEL 2015551212/RATE-$0.00/CONF-/PICKUP-209 MADISON ST SUITE 400"ALEXANDRIA"VA"22314 AT 0900/DROPOFF-DCA AIRPORT/52695871/RESERVATION L1
Abacus:
1 OTH LM 14MAY M GK1 DCA/PCI QA TEST/TEL 201 555 1212/RATE-$0.00/CONF-/PICKUP-209 MADISON ST SUITE 400 ALEXANDRIAVA 22314 AT 0900/DROPOFF-DCA AIRPORT AT 0915/203121365/RESERVATION L1
Galileo:
TUR ZM AK1 SEA 15DEC-/FALCON DES-TEL 8666932526/RATE-50.00 HOURLY-2 HR MIN/CONF-/PU-18400 AT 0900/DO-SEA/771297634/RES
Amadeus:
2 MIS 1A HK1 LGA 13SEP-LMO CAPITAL LIMOUSINE/TEL-800 225 1656/RATE-USD24.00 FLAT/CONF-132625/PICKUP-55 WALL STREET NEW YORK NY 10005 AT 0530/DROPOFF- LGA AIRPORT AT 0600/RID-132625760
Direct Connect - Ground Transportation - Cancel a reservation
The Cancel Reservation operation is sent to the supplier to cancel a travel reservation on behalf of a user. The Ground Transportation direct connect sends the relevant information to a URI that the travel supplier maintains. The standard location is: https://{servername}/concur/groundtransportation. This URI is configured by the supplier when registering the partner application.
Request
URI
/concur/groundtransportation
Headers
Content-Type header (optional)
- application/xml
Accept header (optional)
- application/xml
Authorization header (required)
The Authorization header must include Base64 encoded basic authentication credentials (login ID and password). The login and password are established when the application connector is registered.
'Authorization: Basic {Base64 encoded LoginID:Password}'
Request Body
The request contains a CC_LimoCancelRequest parent element with the child elements listed in the following table:
| Element | Required/Optional | Description |
|---|---|---|
| ReservationID | Required | The unique identifier for the reservation. |
Example Request
POST /concur/groundtransportation HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml
Content-Length: {length of content body}
<CC_LimoCancelRequest>
<ReservationID>1234</ReservationID>
</CC_LimoCancelRequest>
Response
The supplier responds to the request by supplying the full reservation details, with the updated status.
Content Type
- application/xml
Response Schema
The response will include a CC_LimoCancelReply parent element, with the following child elements:
| Element | Required? | Description |
|---|---|---|
| Error | Y | The error information, if an error occurred. This parent element contains the following child elements: ErrorCode: The code for the error. Will contain one of the following values: 400: Credential related error 800: Reservation cannot be cancelled 900: Unknown error ErrorSource: The source of the error. ErrorDescription:The additional error information. |
| ReservationID | N | The identifier for the reservation. |
| Status | N | The status of the reservation. The value will be one of the following: XB: Cancellation Requested XA: Cancellation Accepted XD: Cancellation Declined |
| ConfNum | N | The confirmation number for the reservation. |
| CancelPolicy | N | The cancellation policy for the reservation. |
| CancelNum | N | The cancellation number for the reservation. |
| PrimaryPassenger | Y | The passenger contact name for the reservation. This parent element contains the following child elements: FirstName: The contact's first name. LastName: The contact's last name. Phone: The contact's phone number. Phone2: The contact's backup phone number. CellPhone: The contact's cell phone number. EmailAddress: The contact's email address. |
| ServiceType | Y | The type of service requested. Will contain one of the following values: 100: Point to point 110: One way to airport 111: One way from airport 120: One way to train station 121: One way from train station 200: Hourly 300: Airport to airport |
| ClassOfService | N | The requested service class. Will contain one of the following values: 100: Normal 200: High 300: Highest If this value is not provided by the user, it will default to 100. |
| PickupLocation | Y | The pick up location. This parent element contains the following child elements: LocationType: One of the following: 100 - Address, 200 - Airport, 300 - Train station. Airport: Refer to the Airport Elements table. Provided if the LocationType = 200. TrainStation: Refer to the Train Station Elements table. Provided if the LocationType = 300. Address: The street address of the location. Provided if the LocationType = 100. City: The location city. State: The location state. Preferably 2 characters, max 10 characters. Country: The location's 2 character ISO 3166-1 alpha-2 country code. Example: US PostalCode: The location postal code. ExtraNotes: Additional notes about the location. Example: Ring doorbell, Holiday Inn, etc. |
| DropoffLocation | Y | The drop off location. This parent element contains the following child elements: LocationType: One of the following: 100 - Address, 200 - Airport, 300 - Train station, 400 - As directed. Airport: Refer to the Airport Elements table. Provided if the LocationType = 200. TrainStation: Refer to the Train Station Elements table. Provided if the LocationType = 300. Address: The street address of the location. Provided if the LocationType = 100. City: The location city. State: The location state. Country: The location's 2 character ISO 3166-1 alpha-2 country code. Example: US PostalCode: The location postal code. ExtraNotes: Additional notes about the location. Example: Apartment Building, gravel driveway, etc. |
| StartDateTime | Y | The time, in GMT, that the reservation must begin. Format: 2015-05-19T18:00:00 |
| EndDateTime | N | The time, in GMT that the reservation will end. Provided for hourly reservations. Format: 2015-05-19T18:00:00 |
| PickupInstructions | N | Additional instructions about the pick up request. |
| DropoffInstructions | N | Additional instructions about the drop off request. |
| LanguageCode | Y | The language of the traveler. Will be one of the following options: en: English en-us: English (US) en-gb: English (UK) fr: French fr-ca: French (Canadian) de: German pt: Portuguese es: Spanish nl: Dutch it: Italian ja: Japanese pl: Polish pt-br: Portuguese (Brazilian) ru: Russian hu: Hungarian ko: Korean sv: Swedish zh-cn: Chinese zh-tw: Traditional Chinese |
| Currency | Y | The 3-letter ISO 4217 currency code for the reservation amount. |
| NumPassengers | N | The number of passengers. |
| RequestedDriver | N | The name of the requested driver, if available. |
| SpecialServiceRequest | N | The details of the special service request, if available. |
| PickupServiceArrangement | N | The details of the pickup arrangement, if available. |
| DropoffServiceArrangement | N | The details of the dropoff arrangement, if available. |
| ExtraStopArrangement | N | The details of the extra stop arrangement, if available. |
| RateInfo | Y | The booked rate details. Refer to the Rate Information Elements table for more information. |
| Vehicle | Y | The vehicle details. This parent element contains the following child elements: VehicleType: One of the following values: 100: Sedan 200: Limo 250: Stretch Limo 300: SUV 350: Stretch SUV 400: Van 450: Mini-Bus 500: Motor Coach 600: Shuttle 700: Trolley 800: Carriage 900: Any Description: The vehicle description. MaxPassengers: The maximum number of passengers for the vehicle. Must be greater than zero. VehicleID: Information to identify the specific vehicle. |
| Vendor | Y | The reservation vendor. This parent element contains the following child elements: VendorCode: The vendor code for the vendor. VendorName: The vendor's name. PhoneNumber: The vendor's phone number. |
| FormOfPayment | Y | The form of payment for the reservation. This parent element contains one of the following child elements: CreditCard: If present, the passenger will pay with credit card. Refer to the Reply Credit Card Elements table for the child elements. Cash: If present, the passenger will pay cash. Check: If present, the passenger will pay with a check. DirectBilling: If present, the passenger will pay through direct billing. |
| RateDisclaimer | N | Disclaimer text about the rate. |
| ProviderFeedback | N | Any additional feedback from the supplier. |
| AccountingInfo | N | The accounting information for the reservation. This parent element contains the following child elements: AccountingField1 through AccountingField5: These fields contain detailed accounting information. |
Rate Information Elements
| Element | Required? | Description |
|---|---|---|
| RateID | Y | The rate identifier. |
| Rate | Y | The BasePrice + ServiceCharge + SurCharge + Tax |
| RateTypeCode | Y | The code for the rate type. Will be one of the following options: F: Flat rate H: Hourly E: Estimated amount N: Currently not available |
| CategoryCode | N | Extra information that will be passed back during sell request to help identify the rate. |
| Currency | Y | The 3-letter ISO 4217 currency code for the rate amount. |
| NoRateText | N | Explanation of rate type. Provided if RateTypeCode = N |
| MinHours | N | The minimum number of hours for the reservation. |
| DiscountType | N | The type of discount applied. |
| BasePrice | N | The reservation price without taxes, surcharges or service charges. |
| ServiceCharge | N | The service charge for the reservation. |
| SurCharge | N | This element contains the desc attribute, with text describing the reason for the surcharge. Example: <SurCharge desc="fuel"> |
| Tax | N | The reservation tax. |
| ExtraPickupCharge | N | Any additional fees for the pickup service. |
| ExtraDropoffCharge | N | Any additional fees for the dropoff service. |
| OptionalExtraStopCharge | N | The charge for any additional stops. |
| OptionalExtraTimeCharge | N | The charge for each additional hour. |
Reply Credit Card Elements
| Element | Required? | Description |
|---|---|---|
| Type | Y | The card type. |
| Number | Y | The card number. |
| Expiration | Y | The card expiration date. Format: 2013-02-19 |
Example of Successful Response
HTTPS/1.1 200 OK
Content-Type: application/xml
Content-Length: {length of content body}
<CC_LimoCancelReply>
<Error>
<ErrorCode />
<ErrorSource />
<ErrorDescription />
</Error>
<ReservationID>1234</ReservationID>
<Status>XB</Status>
<ConfNum>4444</ConfNum>
<CancelPolicy />
<CancelNum>55555</CancelNum>
<PrimaryPassenger>
<FirstName>Chris</FirstName>
<LastName>Miller</LastName>
<Phone>5551234567</Phone>
<Phone2>5551234568</Phone2>
<CellPhone>5551234569</CellPhone>
<EmailAddress>cmiller@example.com</EmailAddress>
</PrimaryPassenger>
<ServiceType>110</ServiceType>
<ClassOfService />
<PickupLocation>
<LocationType>100</LocationType>
<Airport>
<AirportCode />
<Flight>
<CarrierCode />
<FlightNumber />
<ArrivalDateTime />
</Flight>
</Airport>
<TrainStation>
<StationCode />
<StationName />
<City />
<State />
<Train>
<CarrierCode />
<CarrierName />
<TrainNumber />
<ArrivalDateTime />
</Train>
</TrainStation>
<Address>209 Madison St</Address>
<City>Alexandria</City>
<State>VA</State>
<Country>US</Country>
<PostalCode>22314</PostalCode>
<ExtraNotes />
</PickupLocation>
<DropoffLocation>
<LocationType>200</LocationType>
<Airport>
<AirportCode>DCA</AirportCode>
<Flight>
<CarrierCode>UA</CarrierCode>
<FlightNumber>333</FlightNumber>
<DepartureDateTime>2012-02-19T11:29:00</DepartureDateTime>
</Flight>
</Airport>
<TrainStation>
<StationCode />
<StationName />
<City />
<State />
<Train>
<CarrierCode />
<CarrierName />
<TrainNumber />
<DepartureDateTime />
</Train>
</TrainStation>
<Address />
<City />
<State />
<Country />
<PostalCode />
<ExtraNotes />
</DropoffLocation>
<StartDateTime>2012-02-19T09:00:00</StartDateTime>
<EndDateTime />
<PickupInstructions>pick me up</PickupInstructions>
<DropoffInstructions>None</DropoffInstructions>
<LanguageCode>en-us</LanguageCode>
<Currency>USD</Currency>
<NumPassengers>1</NumPassengers>
<RequestedDriver />
<SpecialServiceRequest />
<PickupServiceArrangement />
<DropoffServiceArrangement />
<ExtraStopArrangement />
<RateInfo>
<RateID>5</RateID>
<Rate>42.50</Rate>
<RateTypeCode>E</RateTypeCode>
<CategoryCode />
<MinHours />
<Currency>US</Currency>
<NoRateText />
<DiscountType />
<BasePrice>35.00</BasePrice>
<ServiceCharge>5.00</ServiceCharge>
<SurCharge desc="fuel">1.00</SurCharge>
<Tax>1.50</Tax>
<ExtraPickupCharge />
<ExtraDropoffCharge />
<OptionalExtraStopCharge />
<OptionalExtraTimeCharge />
<Message />
</RateInfo>
<RateDisclaimer />
<Vehicle>
<VehicleType>100</VehicleType>
<Description>This is a Sedan.</Description>
<MaxPassengers>1</MaxPassengers>
<VehicleID>12</VehicleID>
</Vehicle>
<Vendor>
<VendorCode>LML</VendorCode>
<VendorName>LimoVendor</VendorName>
<PhoneNumber>4354654654</PhoneNumber>
</Vendor>
<ProviderFeedback />
<FormOfPayment>
<Cash />
<Check />
<DirectBilling />
<CreditCard>
<Type>VI</Type>
<Number>XXXXXXXXXXXX1111</Number>
<Expiration>2013-02-19</Expiration>
</CreditCard>
</FormOfPayment>
<AccountingInfo>
<AccountingField1>715</AccountingField1>
<AccountingField2>temp@outtask.com</AccountingField2>
<AccountingField3>11</AccountingField3>
<AccountingField4>Development</AccountingField4>
<AccountingField5/>
</AccountingInfo>
</CC_LimoCancelReply>
Direct Connect - Ground Transportation - Post a reservation detail search
Request
The following request is sent to the supplier when the Travel user selects a ground transportation reservation to get additional details.
URI
The Ground Transportation direct connect sends the relevant information to a URI that the travel supplier maintains. The standard location is:
https://{servername}/concur/groundtransportation
The URI is configured by the supplier when registering the partner application.
Request Headers - Required
Authorization header with OAuth credentials. Refer to the OAuth documentation for more information.
Request Headers - Optional
None
Request Body
The request will contain a CC_LimoReservationDetailRequest parent element, containing the following child element:
| Element Name | Required/Optional | Data Type | Description |
|---|---|---|---|
| ReservationID | The unique identifier for the reservation. Returned in the ReservationID element by the response of the Post Reservation Sell function. |
XML Example Request
POST /concur/groundtransportation HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml
Content-Length: {length of content body}
<CC_LimoReservationDetailRequest>
<ReservationID>1234</ReservationID>
</CC_LimoReservationDetailRequest>
Response
The supplier responds to the request by supplying the full reservation details.
Content Type
application/xml
Response Schema
The response will include a CC_LimoReservationDetailReply parent element, with the following child elements:
| Element Name | Required/Optional | Data Type | Description |
|---|---|---|---|
| Error | Y | The error information, if an error occurred. For information about the child elements of this parent element, see the Error elements table. | |
| ReservationID | N | The identifier for the reservation. | |
| Status | N | The status of the reservation. The value will be one of the following: RB: Reservation Pending RA: Reservation Accepted (Reserved) RD: Reservation Declined XB: Cancellation Pending XA: Cancellation Confirmed (Cancelled) XD: Cancellation Declined |
|
| ConfNum | N | The confirmation number for the reservation. | |
| CancelPolicy | N | The cancellation policy for the reservation. | |
| CancelNum | N | The cancellation number for the reservation. | |
| PrimaryPassenger | Y | The passenger contact name for the reservation. For information about the child elements of this parent element, see the PrimaryPassenger elements table. | |
| ServiceType | Y | The type of service requested. Will contain one of the following values: 100: Point to point 110: One way to airport 111: One way from airport 120: One way to train station 121: One way from train station 200: Hourly 300: Airport to airport |
|
| ClassOfService | N | The requested service class. Will contain one of the following values: 100: Normal 200: High 300: Highest If this value is not provided by the user, it will default to 100. |
|
| PickupLocation | Y | The pick up location. For information about the child elements of this parent element, see the PickupLocation elements table. | |
| DropoffLocation | Y | The drop off location. For information about the child elements of this parent element, see the DropoffLocation elements table. | |
| StartDateTime | Y | The time, in GMT, that the reservation must begin. Format: 2015-05-19T18:00:00 | |
| EndDateTime | N | The time, in GMT that the reservation will end. Provided for hourly reservations. Format: 2015-05-19T18:00:00 | |
| PickupInstructions | N | Additional instructions about the pick up request. | |
| DropoffInstructions | N | Additional instructions about the drop off request. | |
| LanguageCode | Y | The language of the traveler. Will be one of the following options: en: English en-us: English (US) en-gb: English (UK) fr: French fr-ca: French (Canadian) de: German pt: Portuguese es: Spanish nl: Dutch it: Italian ja: Japanese pl: Polish bt-br: Portuguese (Brazilian) ru: Russian hu: Hungarian ko: Korean sv: Swedish zh-cn: Chinese zh-tw: Traditional Chinese |
|
| Currency | Y | The 3-letter ISO 4217 currency code for the reservation amount. | |
| NumPassengers | N | The number of passengers. | |
| RequestedDriver | N | The name of the requested driver, if available. | |
| SpecialServiceRequest | N | The details of the special service request, if available. | |
| PickupServiceArrangement | N | The details of the pickup arrangement, if available. | |
| DropoffServiceArrangement | N | The details of the dropoff arrangement, if available. | |
| ExtraStopArrangement | N | The details of the extra stop arrangement, if available. | |
| RateInfo | Y | The booked rate details. Refer to the Rate Information elements table for more information. | |
| Vehicle | Y | The vehicle details. For information about the child elements of this parent element, see the Vehicle elements table. | |
| Vendor | Y | The reservation vendor. For information about the child elements of this parent element, see the Vendor elements table. | |
| FormOfPayment | Y | The form of payment for the reservation. For information about the child elements of this parent element, see the FormOfPayment elements table. | |
| RateDisclaimer | N | Disclaimer text about the rate. | |
| ProviderFeedback | N | Any additional feedback from the supplier. | |
| AccountingInfo | N | The accounting information for the reservation. This parent element contains the following child elements: AccountingField1 through AccountingField5 |
Error Child Elements
| Element Name | Required/Optional | Data Type | Description |
|---|---|---|---|
| ErrorCode | The code for the error. Will contain one of the following values: 400: Credential related error 700: Reservation not available 900: Unknown error |
||
| ErrorSource | The source of the error. | ||
| ErrorDescription | The additional error information. |
PrimaryPassenger Child Element
| Element Name | Required/Optional | Data Type | Description |
|---|---|---|---|
| FirstName | The contact's first name. | ||
| LastName | The contact's last name. | ||
| Phone | The contact's phone number. | ||
| Phone2 | The contact's backup phone number. | ||
| CellPhone | The contact's cell phone number. | ||
| EmailAddress | The contact's email address. |
PickupLocation
| Element Name | Required/Optional | Data Type | Description |
|---|---|---|---|
| LocationType | One of the following: 100 - Address, 200 - Airport, 300 - Train station. | ||
| Airport | Refer to the Airport elements table. Provided if the LocationType = 200. | ||
| TrainStation | Refer to the Train Station elements table. Provided if the LocationType = 300. | ||
| Address | The street address of the location. Provided if the LocationType = 100. | ||
| City | The location city. | ||
| State | The location state. Preferably 2 characters, max 10 characters. | ||
| Country | The location's 2 character ISO 3166-1 alpha-2 country code. Example: US | ||
| PostalCode | The location postal code. | ||
| ExtraNotes | Additional notes about the location. Example: Ring doorbell, Holiday Inn, etc. |
DropoffLocation
| Element Name | Required/Optional | Data Type | Description |
|---|---|---|---|
| LocationType | One of the following: 100 - Address, 200 - Airport, 300 - Train station, 400 - As directed. | ||
| Airport | Refer to the Airport elements table. Provided if the LocationType = 200. | ||
| TrainStation | Refer to the Train Station elements table. Provided if the LocationType = 300. | ||
| Address | The street address of the location. Provided if the LocationType = 100. | ||
| City | The location city. | ||
| State | The location state. Preferably 2 characters, max 10 characters. | ||
| Country | The location's 2 character ISO 3166-1 alpha-2 country code. Example: US | ||
| PostalCode | The location postal code. | ||
| ExtraNotes | Additional notes about the location. Example: Apartment Building, gravel driveway, etc. |
Vehicle Child Elements
| Element Name | Required/Optional | Data Type | Description |
|---|---|---|---|
| VehicleType | One of the following values: 100: Sedan 200: Limo 250: Stretch Limo 300: SUV 350: Stretch SUV 400: Van 450: Mini-Bus 500: Motor Coach 600: Shuttle 700: Trolley 800: Carriage 900: Any |
||
| Description | The vehicle description. | ||
| MaxPassengers | The maximum number of passengers for the vehicle. Must be greater than zero. | ||
| VehicleID | Information to identify the specific vehicle. |
Vendor Child Elements
| Element Name | Required/Optional | Data Type | Description |
|---|---|---|---|
| VendorCode | The vendor code for the vendor. | ||
| VendorName | The vendor's name. | ||
| PhoneNumber | The vendor's phone number. |
FormOfPayment Child Elements
| Element Name | Required/Optional | Data Type | Description |
|---|---|---|---|
| CreditCard | If present, the passenger will pay with credit card. Refer to the Reply Credit Card Elements table for the child elements. | ||
| Cash | If present, the passenger will pay cash. | ||
| Check | If present, the passenger will pay with a check. | ||
| DirectBilling | If present, the passenger will pay through direct billing. |
Rate Information Elements
| Element Name | Required/Optional | Data Type | Description |
|---|---|---|---|
| RateID | Y | The rate identifier. | |
| Rate | Y | The BasePrice + ServiceCharge + SurCharge + Tax | |
| RateTypeCode | Y | The code for the rate type. Will be one of the following options: F: Flat rate H: Hourly E: Estimated amount N: Currently not available |
|
| CategoryCode | N | Extra information that will be passed back during sell request to help identify the rate. | |
| Currency | Y | The 3-letter ISO 4217 currency code for the rate amount. | |
| NoRateText | N | Explanation of rate type. Provided if RateTypeCode = N | |
| MinHours | N | The minimum number of hours for the reservation. | |
| DiscountType | N | The type of discount applied. | |
| BasePrice | N | The reservation price without taxes, surcharges or service charges. | |
| ServiceCharge | N | The service charge for the reservation. | |
| SurCharge | N | This element contains the desc attribute, with text describing the reason for the surcharge. Example: <SurCharge desc="fuel"> |
|
| Tax | N | The reservation tax. | |
| ExtraPickupCharge | N | Any additional fees for the pickup service. | |
| ExtraDropoffCharge | N | Any additional fees for the drop off service. | |
| OptionalExtraStopCharge | N | The charge for any additional stops. | |
| OptionalExtraTimeCharge | N | The charge for each additional hour. |
Reply Credit Card Elements
| Element Name | Required/Optional | Data Type | Description |
|---|---|---|---|
| Type | Y | The card type. | |
| Number | Y | The card number. | |
| Expiration | Y | The card expiration date. Format: 2013-02-19. |
Airport Elements
| Element Name | Required/Optional | Data Type | Description |
|---|---|---|---|
| AirportCode | The IATA code for the airport. | ||
| Flight | The flight information. For information about the child elements of this parent element, see the Flight elements table. |
Flight Child Elements
| Element Name | Required/Optional | Data Type | Description |
|---|---|---|---|
| CarrierCode | The airline code. | ||
| FlightNumber | The flight number. | ||
| ArrivalDateTime | The flight arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00 | ||
| DepartureDateTime | The flight departure time. Only provided for the DropoffLocation element. Format: 2015-05-19T18:00:00 |
Train Station Elements
| Element Name | Required/Optional | Data Type | Description |
|---|---|---|---|
| StationCode | The station code. | ||
| StationName | The name of the station. | ||
| City | The city the station is located in. | ||
| State | The state the station is located in. Preferably 2 characters, max 10 characters. | ||
| Train | The train information. For information about the child elements of this parent element, see the Train elements table. |
Train Child Elements
| Element Name | Required/Optional | Data Type | Description |
|---|---|---|---|
| CarrierCode | The code of the train carrier. | ||
| CarrierName | The name of the train carrier. | ||
| TrainNumber | The train number. | ||
| ArrivalDateTime | The train arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00 | ||
| DepartureDateTime | The train departure time. Only provided for the DropoffLocation element. Format: 2015-05-19T18:00:00 |
XML Example of Successful Response
HTTPS/1.1 200 OK
Content-Type: application/xml
Content-Length: {length of content body}
<CC_LimoReservationDetailReply>
<Error>
<ErrorCode />
<ErrorSource />
<ErrorDescription />
</Error>
<ReservationID>1234</ReservationID>
<Status>RB</Status>
<ConfNum>4444</ConfNum>
<CancelPolicy />
<CancelNum>55555</CancelNum>
<PrimaryPassenger>
<FirstName>Chris</FirstName>
<LastName>Miller</LastName>
<Phone>5551234567</Phone>
<Phone2>5551234568</Phone2>
<CellPhone>5551234569</CellPhone>
<EmailAddress>cmiller@example.com</EmailAddress>
</PrimaryPassenger>
<ServiceType>110</ServiceType>
<ClassOfService />
<PickupLocation>
<LocationType>100</LocationType>
<Airport>
<AirportCode />
<Flight>
<CarrierCode />
<FlightNumber />
<ArrivalDateTime />
</Flight>
</Airport>
<TrainStation>
<StationCode />
<StationName />
<City />
<State />
<Train>
<CarrierCode />
<CarrierName />
<TrainNumber />
<ArrivalDateTime />
</Train>
</TrainStation>
<Address>209 Madison St</Address>
<City>Alexandria</City>
<State>VA</State>
<Country>US</Country>
<PostalCode>22314</PostalCode>
<ExtraNotes />
</PickupLocation>
<DropoffLocation>
<LocationType>200</LocationType>
<Airport>
<AirportCode>DCA</AirportCode>
<Flight>
<CarrierCode>UA</CarrierCode>
<FlightNumber>333</FlightNumber>
<DepartureDateTime>2012-02-19T11:29:00</DepartureDateTime>
</Flight>
</Airport>
<TrainStation>
<StationCode />
<StationName />
<City />
<State />
<Train>
<CarrierCode />
<CarrierName />
<TrainNumber />
<DepartureDateTime />
</Train>
</TrainStation>
<Address />
<City />
<State />
<Country />
<PostalCode />
<ExtraNotes />
</DropoffLocation>
<StartDateTime>2012-02-19T09:00:00</StartDateTime>
<EndDateTime />
<PickupInstructions>pick me up</PickupInstructions>
<DropoffInstructions>None</DropoffInstructions>
<LanguageCode>en-us</LanguageCode>
<Currency>USD</Currency>
<NumPassengers>1</NumPassengers>
<RequestedDriver />
<SpecialServiceRequest />
<PickupServiceArrangement />
<DropoffServiceArrangement />
<ExtraStopArrangement />
<RateInfo>
<RateID>5</RateID>
<Rate>42.50</Rate>
<RateTypeCode>E</RateTypeCode>
<CategoryCode />
<MinHours />
<Currency>USD</Currency>
<NoRateText />
<DiscountType />
<BasePrice>35.00</BasePrice>
<ServiceCharge>5.00</ServiceCharge>
<SurCharge desc="fuel">1.00</SurCharge>
<Tax>1.50</Tax>
<ExtraPickupCharge />
<ExtraDropoffCharge />
<OptionalExtraStopCharge />
<OptionalExtraTimeCharge />
<Message />
</RateInfo>
<RateDisclaimer />
<Vehicle>
<VehicleType>100</VehicleType>
<Description>This is a Sedan.</Description>
<MaxPassengers>1</MaxPassengers>
<VehicleID>12</VehicleID>
</Vehicle>
<Vendor>
<VendorCode>LML</VendorCode>
<VendorName>LimoVendor</VendorName>
<PhoneNumber>4354654654</PhoneNumber>
</Vendor>
<ProviderFeedback />
<FormOfPayment>
<Cash />
<Check />
<DirectBilling />
<CreditCard>
<Type>VI</Type>
<Number>XXXXXXXXXXXX1111</Number>
<Expiration>2013-02-19</Expiration>
</CreditCard>
</FormOfPayment>
<AccountingInfo>
<AccountingField1>715</AccountingField1>
<AccountingField2>temp@outtask.com</AccountingField2>
<AccountingField3>11</AccountingField3>
<AccountingField4>Development</AccountingField4>
<AccountingField5/>
</AccountingInfo>
</CC_LimoReservationDetailReply>
Direct Connect - Ground Transportation - Post a reservation sell request
A post reservation sell request is sent when a Travel user attempts to book a ground transportation reservation.
Request
Supported Accept Types
application/xml
Request URI
The Ground Transportation direct connect sends the relevant information to a URI that the travel supplier maintains. The standard location is:
https://{servername}/concur/groundtransportation
The URI is configured by the supplier when registering the partner application.
Headers
Authorization Header
Authentication header with Base64 encoded basic authentication credentials (login ID and password) is required. The basic authentication credentials are established during the application review process.
Authorization: Basic {Base64 encoded LoginID:Password}
Request Body
The request will contain a CC_LimoSellRequest parent element, containing the following child elements.
CorporateClient
The corporate client the booking is on behalf of. This parent element contains the following child element:
- CompanyCode: The code for the company of the client.
Booker
The user booking the reservation. This parent element contains the following child elements:
- UserID: The user's SAP Concur user ID.
- EmailAddress: The user's email address.
- Phone: The user's contact number.
PrimaryPassenger
The passenger contact name for the reservation. This parent element contains the following child elements:
- FirstName: The contact's first name
- LastName: The contact's last name
- Phone: The contact's phone number
- Phone2: The contact's backup phone number
- CellPhone: The contact's cell phone number
- EmailAddress: The contact's email address
ServiceType
The type of service requested. Will contain one of the following values:
- 100: Point to point
- 110: One way to airport
- 111: One way from airport
- 120: One way to train station
- 121: One way from train station
- 200: Hourly
- 300: Airport to airport
ClassOfService
The requested service class. Will contain one of the following values:
- 100: Normal
- 200: High
- 300: Highest
If this value is not provided by the user, it will default to 100
PickupLocation
The pick up location. This parent element contains the following child elements:
- LocationType: One of the following: 100 - Address, 200 - Airport, 300 - Train station.
- Airport: Refer to the Airport elements table. Provided if the LocationType = 200.
- TrainStation: Refer to the Train Station elements table. Provided if the LocationType = 300.
- Address: The street address of the location. Provided if the LocationType = 100.
- City: The location city.
- State: The location state. Preferably 2 characters, max 10 characters.
- Country: The location's 2 character ISO 3166-1 alpha-2 country code. Example: US
- PostalCode: The location postal code.
- ExtraNotes: Additional notes about the location. Example: Ring doorbell, Holiday Inn, etc.
DropoffLocation
The drop off location. This parent element contains the following child elements:
- LocationType: One of the following: 100 - Address, 200 - Airport, 300 - Train station, 400 - As directed.
- Airport: Refer to the Airport elements table. Provided if the LocationType = 200.
- TrainStation: Refer to the Train Station elements table. Provided if the LocationType = 300.
- Address: The street address of the location. Provided if the LocationType = 100.
- City: The location city.
- State: The location state. Preferably 2 characters, max 10 characters.
- Country: The location's 2 character ISO 3166-1 alpha-2 country code. Example: US
- PostalCode: The location postal code.
- ExtraNotes: Additional notes about the location. Example: Apartment Building, gravel driveway, etc.
StartDateTime
The time, in GMT, that the reservation must begin. Format: 2015-05-19T18:00:00
EndDateTime
The time, in GMT that the reservation will end. Provided for hourly reservations. Format: 2015-05-19T18:00:00
PickupInstructions
Additional instructions about the pick up request.
DropoffInstructions
Additional instructions about the drop off request.
LanguageCode
The language of the traveler. Will be one of the following options:
- en: English
- en-us: English (US)
- en-gb: English (UK)
- fr: French
- fr-ca: French (Canadian)
- de: German
- pt: Portuguese
- es: Spanish
- nl: Dutch
- it: Italian
- ja: Japanese
- pl: Polish
- pt-br: Portuguese (Brazilian)
- ru: Russian
- hu: Hungarian
- ko: Korean
- sv: Swedish
- zh-cn: Chinese
- zh-tw: Traditional Chinese
Currency
The 3-letter ISO 4217 currency code for the reservation amount.
NumPassengers
The number of passengers.
DiscountCode
The discount code information. This parent element contains the following child elements:
- Corporate ID: The user's corporate ID.
- VendorCode: The user's vendor code.
- DiscountNumber: The user's discount number.
RateInfo
The booked rate. This parent element contains the following child elements:
- RateID: The rate identifier.
- Rate: The total rate, including the BasePrice, ServiceCharge, SurCharge, and Tax.
- RateTypeCode: The code for the rate type. Will be one of the following options:
- F: Flat rate
- H: Hourly
- E: Estimated amount
- N: Currently not available
- CategoryCode Extra information that will be passed back during sell request to help identify the rate.
- Currency The 3-letter ISO 4217 currency code for the rate amount.
Vehicle
The vehicle details. This parent element contains the following child elements:
VehicleType: One of the following values:
- 100: Sedan
- 200: Limo
- 250: Stretch Limo
- 300: SUV
- 350: Stretch SUV
- 400: Van
- 450: Mini-Bus
- 500: Motor Coach
- 600: Shuttle
- 700: Trolley
- 800: Carriage
- 900: Any
VehicleID: Information to identify the specific vehicle.
Vendor
The reservation vendor. This parent element contains the following child element:
- VendorCode: The vendor code for the vendor.
FormOfPayment
The form of payment for the reservation. This parent element contains one of the following child elements:
- CreditCard: If present, the passenger will pay with credit card. Refer to the Reply Credit Card elements table for the child elements.
- Cash: If present, the passenger will pay cash.
- Check: If present, the passenger will pay with a check.
- DirectBilling: If present, the passenger will pay through direct billing.
RequestedDriver
The name of the requested driver, if available.
SpecialServiceRequest
The details of the special service request, if available.
PickupServiceArrangement
The details of the pickup arrangement, if available.
DropoffServiceArrangement
The details of the dropoff arrangement, if available.
ExtraStopArrangement
The details of the extra stop arrangement, if available.
RequestedDriver
The name of the requested driver, if available.
Airport Elements
AirportCode
The IATA code for the airport.
Flight: The flight information. This parent element contains the following child elements: * CarrierCode: The airline code. * FlightNumber: The flight number. * ArrivalDateTime: The flight arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00 * DepartureDateTime: The flight departure time. Only provided for the DropoffLocation element. Format: 2015-05-19T18:00:00
Train Station Elements
StationCode
The station code.
StationName
The name of the station.
City
The city the station is located in.
State
The state the station is located in. Preferably 2 characters, max 10 characters.
Train
The train information. This parent element contains the following child elements:
- CarrierCode: The code of the train carrier.
- CarrierName: The name of the train carrier.
- TrainNumber: The train number.
- ArrivalDateTime: The train arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00
- DepartureDateTime: The train arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00
Credit Card Elements
Type
The card type.
Number
The card number.
Expiration
The card expiration date. Format: 2013-02-19
Name
The name on the card.
Address
The street information of the billing address of the car.
City
The city of the billing address of the car.
State
The state of the billing address of the car. Preferably 2 characters, max 10 characters.
Country
The country of the billing address of the car.
PostalCode
The postal code of the billing address of the car.
XML Example Request
POST /concur/groundtransportation HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml
Content-Length: {length of content body}
<CC_LimoSellRequest>
<CorporateClient>
<CompanyCode>339</CompanyCode>
</CorporateClient>
<Booker>
<UserID>55414</UserID>
<EmailAddress>cmiller@example.com</EmailAddress>
<Phone>5551234567</Phone>
</Booker>
<PrimaryPassenger>
<FirstName>Chris</FirstName>
<LastName>Miller</LastName>
<Phone>5551234567</Phone>
<Phone2>5551234568</Phone2>
<CellPhone>5551234569</CellPhone>
<EmailAddress>cmiller@example.com</EmailAddress>
</PrimaryPassenger>
<ServiceType>110</ServiceType>
<ClassOfService>100</ClassOfService>
<StartDateTime>2012-02-19T09:00:00</StartDateTime>
<EndDateTime />
<PickupInstructions>pick me up</PickupInstructions>
<DropoffInstructions>None</DropoffInstructions>
<LanguageCode>en-us</LanguageCode>
<RateInfo>
<RateID>1</RateID>
<Rate>42.50</Rate>
<RateTypeCode>100</RateTypeCode>
<CategoryCode />
<Currency>USD</Currency>
</RateInfo>
<Vehicle>
<VehicleType>Sedan</VehicleType>
<Description>This is a Sedan.</Description>
<MaxPassengers>1</MaxPassengers>
<VehicleID>12</VehicleID>
</Vehicle>
<Vendor>
<VendorCode>LML</VendorCode>
<VendorName>LimoVendor</VendorName>
<PhoneNumber>4354654654</PhoneNumber>
</Vendor>
<FormOfPayment>
<CreditCard>
<Type>VI</Type>
<Number>xxxxxxxxxxxx1111</Number>
<Expiration>2013-02-19</Expiration>
<NameOnCard />
<Address>209 MADISON ST. #400</Address>
<City>ALEXANDRIA</City>
<State>VA</State>
<Country>US</Country>
<PostalCode>22314</PostalCode>
</CreditCard>
</FormOfPayment>
<RequestedDriver />
<AccountingInfo>
<AccountingField1>715</AccountingField1>
<AccountingField2>temp@outtask.com</AccountingField2>
<AccountingField3>11</AccountingField3>
<AccountingField4>Development</AccountingField4>
<AccountingField5/>
</AccountingInfo>
</CC_LimoSellRequest>
Response
The supplier responds to the Sell request by returning the details of the booked reservation.
Supported Content Types
application/xml
Content Body
The response will include a CC_LimoSellReply parent element, with the following child elements:
| Element | Required? | Description |
|---|---|---|
| Error | Y | The error information, if an error occurred. For information about the child elements of this parent element, see the Error elements table below. |
| ReservationID | N | The identifier for the reservation. |
| Status | N | The status of the reservation. The value will be one of the following: RB: Reservation Pending RA: Reservation Accepted (Reserved) RD: Reservation Declined |
| ConfNum | N | The confirmation number for the reservation. |
| CancelPolicy | N | The cancellation policy for the reservation. |
| CancelNum | N | The cancellation number for the reservation. |
| PrimaryPassenger | Y | The passenger contact name for the reservation. For information about the child elements of this parent element, see the PrimaryPassenger elements table below. |
| ServiceType | Y | The type of service requested. Will contain one of the following values: 100: Point to point 110: One way to airport 111: One way from airport 120: One way to train station 121: One way from train station 200: Hourly 300: Airport to airport |
| ClassOfService | N | The requested service class. Will contain one of the following values: 100: Normal 200: High 300: Highest If this value is not provided by the user, it will default to 100. |
| PickupLocation | Y | The pick up location. For information about the child elements of this parent element, see the PickupLocation elements table below. |
| DropoffLocation | Y | The drop off location. For information about the child elements of this parent element, see the DropoffLocation elements table below. |
| StartDateTime | Y | The time, in GMT, that the reservation must begin. Format: 2015-05-19T18:00:00 |
| EndDateTime | N | The time, in GMT that the reservation will end. Provided for hourly reservations. Format: 2015-05-19T18:00:00 |
| PickupInstructions | N | Additional instructions about the pick up request. |
| DropoffInstructions | N | Additional instructions about the drop off request. |
| LanguageCode | Y | The language of the traveler. Will be one of the following options: en: English en-us: English (US) en-gb: English (UK) fr: French fr-ca: French (Canadian) de: German pt: Portuguese es: Spanish nl: Dutch it: Italian ja: Japanese pl: Polish pt-br: Portuguese (Brazilian) ru: Russian hu: Hungarian ko: Korean sv: Swedish zh-cn: Chinese zh-tw: Traditional Chinese |
| Currency | Y | The 3-letter ISO 4217 currency code for the reservation amount. |
| NumPassengers | N | The number of passengers. |
| RequestedDriver | N | The name of the requested driver, if available. |
| SpecialServiceRequest | N | The details of the special service request, if available. |
| PickupServiceArrangement | N | The details of the pickup arrangement, if available. |
| DropoffServiceArrangement | N | The details of the dropoff arrangement, if available. |
| ExtraStopArrangement | N | The details of the extra stop arrangement, if available. |
| RateInfo | Y | The booked rate details. Refer to the Rate Information elements table below for more information. |
| Vehicle | Y | The vehicle details. For information about the child elements of this parent element, see the Vehicle elements table below. |
| Vendor | Y | The reservation vendor. For information about the child elements of this parent element, see the Vendor elements table below. |
| FormOfPayment | Y | The form of payment for the reservation. For information about the child elements of this parent element, see the FormOfPayment elements table below. |
| RateDisclaimer | N | Disclaimer text about the rate. |
| ProviderFeedback | N | Any additional feedback from the supplier. |
| AccountingInfo | N | The accounting information for the reservation. This parent element contains one or more AccountingField elements: AccountingField1 through AccountingField5. These fields contain detailed accounting information. |
Error Elements
| Element | Description |
|---|---|
| ErrorCode | The code for the error. Will contain one of the following values: 100: Pickup/dropoff location related error 200: Pickup/dropoff time related error 300: Other request parameters related error 400: Credential related error 500: No rate/service available 600: FOP related error 900: Unknown error |
| ErrorSource | The source of the error. |
| ErrorDescription | The additional error information. |
PrimaryPassenger Elements
| Element | Description |
|---|---|
| FirstName | The contact's first name. |
| LastName | The contact's last name. |
| Phone | The contact's phone number. |
| Phone2 | The contact's backup phone number. |
| CellPhone | The contact's cell phone number. |
| EmailAddress | The contact's email address. |
Rate Information Elements
| Element Name | Required? | Data Type | Description |
|---|---|---|---|
| RateID | Y | The rate identifier. | |
| Rate | Y | The BasePrice + ServiceCharge + SurCharge + Tax | |
| RateTypeCode | Y | The code for the rate type. Will be one of the following options: F: Flat rate H: Hourly E: Estimated amount N: Currently not available |
|
| CategoryCode | N | Extra information that will be passed back during sell request to help identify the rate. | |
| Currency | Y | The 3-letter ISO 4217 currency code for the rate amount. | |
| NoRateText | N | Explanation of rate type. Provided if RateTypeCode = N | |
| MinHours | N | The minimum number of hours for the reservation. | |
| DiscountType | N | The type of discount applied. | |
| BasePrice | N | The reservation price without taxes, surcharges or service charges. | |
| ServiceCharge | N | The service charge for the reservation. | |
| SurCharge | N | This element contains the desc attribute, with text describing the reason for the surcharge. Example: <SurCharge desc="fuel"> |
|
| Tax | N | The reservation tax. | |
| ExtraPickupCharge | N | Any additional fees for the pickup service. | |
| ExtraDropoffCharge | N | Any additional fees for the drop off service. | |
| OptionalExtraStopCharge | N | The charge for any additional stops. | |
| OptionalExtraTimeCharge | N | The charge for each additional hour. |
Vehicle Elements
| Element | Description |
|---|---|
| VehicleType | One of the following values: 100: Sedan 200: Limo 250: Stretch Limo 300: SUV 350: Stretch SUV 400: Van 450: Mini-Bus 500: Motor Coach 600: Shuttle 700: Trolley 800: Carriage 900: Any |
| VehicleID | Information to identify the specific vehicle. |
Vendor Elements
| Element | Description |
|---|---|
| VendorCode | The vendor code for the vendor. |
| VendorName | The vendor's name. |
| PhoneNumber | The vendor's phone number. |
FormOfPayment Elements
| Element | Description |
|---|---|
| CreditCard | If present, the passenger will pay with credit card. Refer to the Reply Credit Card elements table for the child elements. |
| Cash | If present, the passenger will pay cash. |
| Check | If present, the passenger will pay with a check. |
| DirectBilling | If present, the passenger will pay through direct billing. |
Reply Credit Card Elements
| Element Name | Required? | Description |
|---|---|---|
| Type | Y | The card type. |
| Number | Y | The card number. |
| Expiration | Y | The card expiration date. Format: 2013-02-19 |
XML Example of Successful Response
HTTPS/1.1 200 OK
Content-Type: application/xml
Content-Length: {length of content body}
<CC_LimoSellReply>
<Error>
<ErrorCode />
<ErrorSource />
<ErrorDescription />
</Error>
<ReservationID>1234</ReservationID>
<Status>RB</Status>
<ConfNum>4444</ConfNum>
<CancelPolicy />
<CancelNum>55555</CancelNum>
<PrimaryPassenger>
<FirstName>Chris</FirstName>
<LastName>Miller</LastName>
<Phone>5551234567</Phone>
<Phone2>5551234568</Phone2>
<CellPhone>5551234569</CellPhone>
<EmailAddress>cmiller@example.com</EmailAddress>
</PrimaryPassenger>
<ServiceType>110</ServiceType>
<ClassOfService />
<PickupLocation>
<LocationType>100</LocationType>
<Airport>
<AirportCode />
<Flight>
<CarrierCode />
<FlightNumber />
<ArrivalDateTime />
</Flight>
</Airport>
<TrainStation>
<StationCode />
<StationName />
<City />
<State />
<Train>
<CarrierCode />
<CarrierName />
<TrainNumber />
<ArrivalDateTime />
</Train>
</TrainStation>
<Address>209 Madison St</Address>
<City>Alexandria</City>
<State>VA</State>
<Country>US</Country>
<PostalCode>22314</PostalCode>
<ExtraNotes />
</PickupLocation>
<DropoffLocation>
<LocationType>200</LocationType>
<Airport>
<AirportCode>DCA</AirportCode>
<Flight>
<CarrierCode>UA</CarrierCode>
<FlightNumber>333</FlightNumber>
<DepartureDateTime>2012-02-19T11:29:00</DepartureDateTime>
</Flight>
</Airport>
<TrainStation>
<StationCode />
<StationName />
<City />
<State />
<Train>
<CarrierCode />
<CarrierName />
<TrainNumber />
<DepartureDateTime />
</Train>
</TrainStation>
<Address />
<City />
<State />
<Country />
<PostalCode />
<ExtraNotes />
</DropoffLocation>
<StartDateTime>2012-02-19T09:00:00</StartDateTime>
<EndDateTime />
<PickupInstructions>pick me up</PickupInstructions>
<DropoffInstructions>None</DropoffInstructions>
<LanguageCode>en-us</LanguageCode>
<Currency>USD</Currency>
<NumPassengers>1</NumPassengers>
<RequestedDriver />
<SpecialServiceRequest />
<PickupServiceArrangement />
<DropoffServiceArrangement />
<ExtraStopArrangement />
<RateInfo>
<RateID>5</RateID>
<Rate>42.50</Rate>
<RateTypeCode>E</RateTypeCode>
<CategoryCode />
<MinHours />
<Currency>US</Currency>
<NoRateText />
<DiscountType />
<BasePrice>35.00</BasePrice>
<ServiceCharge>5.00</ServiceCharge>
<SurCharge desc="fuel">1.00</SurCharge>
<Tax>1.50</Tax>
<ExtraPickupCharge />
<ExtraDropoffCharge />
<OptionalExtraStopCharge />
<OptionalExtraTimeCharge />
<Message />
</RateInfo>
<RateDisclaimer />
<Vehicle>
<VehicleType>100</VehicleType>
<Description>This is a Sedan.</Description>
<MaxPassengers>1</MaxPassengers>
<VehicleID>12</VehicleID>
</Vehicle>
<Vendor>
<VendorCode>LML</VendorCode>
<VendorName>LimoVendor</VendorName>
<PhoneNumber>4354654654</PhoneNumber>
</Vendor>
<ProviderFeedback />
<FormOfPayment>
<Cash />
<Check />
<DirectBilling />
<CreditCard>
<Type>VI</Type>
<Number>XXXXXXXXXXXX1111</Number>
<Expiration>2013-02-19</Expiration>
</CreditCard>
</FormOfPayment>
<AccountingInfo>
<AccountingField1>715</AccountingField1>
<AccountingField2>temp@outtask.com</AccountingField2>
<AccountingField3>11</AccountingField3>
<AccountingField4>Development</AccountingField4>
<AccountingField5/>
</AccountingInfo>
</CC_LimoSellReply>
Direct Connect - Ground Transportation - Post a transportation search
A post transportation search request is sent when the Travel user searches for ground transportation.
Request
URI
The Ground Transportation direct connect sends the relevant information to a URI that the travel supplier maintains. The standard location is:
https://{servername}/concur/groundtransportation
The URI is configured by the supplier when registering the partner application.
Headers
Accept Header
application/xml
Authorization Header
Authorization header with OAuth credentials.
Request Body
The request will contain a CC_LimoSearchRequest parent element, containing the following child elements.
ServiceType: The type of service requested. Will contain one of the following values:
100: Point to point
110: One way to airport
111: One way from airport
120: One way to train station
121: One way from train station
200: Hourly
300: Airport to airport
ClassOfService: The requested service class. Will contain one of the following values:
100: Normal
200: High
300: Highest
If this value is not provided by the user, it will default to 100.
PickupLocation: The pick up location. This parent element contains the following child elements:
PickupLocation Elements
| Element | Description |
|---|---|
| LocationType | One of the following: 100 - Address, 200 - Airport, 300 - Train station. |
| Airport | Refer to the Airport Elements table. Provided if the LocationType = 200. |
| TrainStation | Refer to the Train Station Elements table. Provided if the LocationType = 300. |
| Address | The street address of the location. Provided if the LocationType = 100. |
| City | The location city. |
| State | The location state. Preferably 2 characters, max 10 characters. |
| Country | The location's 2 character ISO 3166-1 alpha-2 country code. Example: US |
| PostalCode | The location postal code. |
| ExtraNotes | Additional notes about the location. Example: Ring doorbell, Holiday Inn, etc. |
DropoffLocation: The drop off location. This parent element contains the following child elements:
DropoffLocation Elements
| Element | Description |
|---|---|
| LocationType | One of the following: 100 - Address, 200 - Airport, 300 - Train station. |
| Airport | Refer to the Airport Elements table. Provided if the LocationType = 200. |
| TrainStation | Refer to the Train Station Elements table. Provided if the LocationType = 300. |
| Address | The street address of the location. Provided if the LocationType = 100. |
| City | The location city. |
| State | The location state. Preferably 2 characters, max 10 characters. |
| Country | The location's 2 character ISO 3166-1 alpha-2 country code. Example: US |
| PostalCode | The location postal code. |
| ExtraNotes | Additional notes about the location. Example: Apartment building, gravel driveway, etc. |
StartDateTime: The time, in GMT, that the reservation must begin. Format: 2015-05-19T18:00:00
EndDateTime: The time, in GMT that the reservation will end. Provided for hourly reservations. Format: 2015-05-19T18:00:00
PickupInstructions: Additional instructions about the pick up request.
DropoffInstructions: Additional instructions about the drop off request.
LanguageCode: The language of the traveler. Will be one of the following options:
en: English
en-us: English (US)
en-gb: English (UK)
fr: French
fr-ca: French (Canadian)
de: German
pt: Portuguese
es: Spanish
nl: Dutch
it: Italian
ja: Japanese
pl: Polish
pt-br: Portuguese (Brazilian)
ru: Russian
hu: Hungarian
ko: Korean
sv: Swedish
zh-cn: Chinese
zh-tw: Traditional Chinese
Currency: The 3-letter ISO 4217 currency code for the reservation amount.
NumPassengers: The number of passengers.
VehicleType: The type of vehicle requested. Will be one of the following options:
100: Sedan
200: Limo
201: Stretch Limo
300: SUV
301: Stretch SUV
400: Van
401: Mini-Bus
402: Bus
500: Motor Coach
501: Antique/Classic
502: Trolley
503: Carriage
600: Shuttle
900: Any
DiscountCode: The discount code information. This parent element contains the following child elements:
DiscountCode Elements
| Element | Description |
|---|---|
| CorporateID | The user's corporate ID. |
| VendorCode | The user's vendor code. |
| DiscountNumber | The user's discount number. |
Airport Elements
AirportCode: The IATA Code for the airport.
Flight: The flight information. This parent element contains the following child elements:
Flight Elements
| Element | Description |
|---|---|
| CarrierCode | The airline code. |
| FlightNumber | The flight number. |
| ArrivalDateTime | The flight arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00 |
| DepartureDateTime | The flight departure time. Only provided for the DropoffLocation element. Format: 2015-05-19T18:00:00 |
Train Station Elements
| Element | Description |
|---|---|
| StationCode | The station code. |
| StationName | The name of the station. |
| City | The city the station is located in. |
| State | The state the station is located in. Preferably 2 characters, max 10 characters. |
| Train | The train information. This parent element contains the following child elements. |
Train Elements
| Element | Description |
|---|---|
| CarrierCode | The code of the train carrier. |
| CarrierName | The name of the train carrier. |
| TrainNumber | The train number. |
| ArrivalDateTime | The train arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00 |
| DepartureDateTime | The train departure time. Only provided for the DropoffLocation element. Format: 2015-05-19T18:00:00 |
Response
The supplier responds to the Limo Search request by returning the details of an available reservation that matches the search criteria.
Content Types
application/xml
Content Body
The response will include a CC_LimoSearchReply parent element, with the following child elements:
Error: The error information, if an error occurred. Required. This parent element contains the following child elements:
Error Elements
| Element | Description |
|---|---|
| ErrorCode | The code for the error. Will contain one of the following values: 100: Pickup/dropoff location related error 200: Pickup/dropoff time related error 300: Other request parameters related error 400: Credential related error 500: No rate/service available 900: Unknown error |
| ErrorSource | The source of the error. |
| ErrorDescription | The additional error information. |
RequestData: This parent element contains a copy of the original request data. Only the ServiceType, PickupLocation, DropoffLocation, and StartDateTime elements are required.
Limos: This parent element contains a Limo child element with the available reservation information. Refer to the Limo Elements table for the details of the child elements of the Limo element.
Limo Elements
RateInfo: The rate information for the limo. Refer to the Rate Information Elements table for more information. Required.
Vehicle: The type of vehicle. Required. This parent element contains the following child elements:
VehicleType: One of the following values:
100: Sedan
200: Limo
250: Stretch Limo
300: SUV
350: Stretch SUV
400: Van
450: Mini-Bus
500: Motor Coach
600: Shuttle
700: Trolley
800: Carriage
900: Any
Description: The detailed description of the vehicle.
MaxPassengers: The maximum number of passengers allowed in the vehicle. Must be greater than zero.
VehicleID: Information to identify the specific vehicle.
Vendor: The reservation vendor. Required. This parent element contains the following child elements:
Vendor Elements
| Element | Description |
|---|---|
| VendorCode | The vendor code for the vendor. |
| VendorName | The vendor's name. |
| PhoneNumber | The vendor's phone number. |
AcceptedFops: The accepted forms of payment. Required. This parent element contains the FormOfPayment child element. The FormOfPayment element contains the allowed forms of payment. The possible child elements are:
FormOfPayment Elements
| Element | Description |
|---|---|
| CreditCard | This element will appear if the Credit Card form of payment is accepted. Contains the Type child element with one of the following values: AX - American Express, CA - Master Card, VI - Visa, DS - Discover Card, DC - Diners Club |
| Cash | This element will appear if the Cash form of payment is accepted. |
| Check | This element will appear if the Check form of payment is accepted. |
| DirectBilling | This element will appear if the Direct Billing form of payment is accepted. |
Rate Information Elements
| Element | Required? | Description |
|---|---|---|
| RateID | Y | The rate identifier. |
| Rate | Y | The BasePrice + ServiceCharge + SurCharge + Tax |
| RateTypeCode | Y | The code for the rate type. Will be one of the following options: F: Flat rate H: Hourly E: Estimated amount N: Currently not available |
| CategoryCode | N | Extra information that will be passed back during sell request to help identify the rate. |
| Currency | Y | The 3-letter ISO 4217 currency code for the rate amount. |
| NoRateText | N | Explanation of rate type. Provided if RateTypeCode = N |
| MinHours | N | The minimum number of hours for the reservation. |
| DiscountType | N | The type of discount applied. |
| BasePrice | N | The reservation price without taxes, surcharges or service charges. |
| ServiceCharge | N | The service charge for the reservation. |
| SurCharge | N | This element contains the desc attribute, with text describing the reason for the surcharge. Example: <SurCharge desc="fuel"> |
| Tax | N | The reservation tax. |
| ExtraPickupCharge | N | Any additional fees for the pickup service. |
| ExtraDropoffCharge | N | Any additional fees for the drop off service. |
| OptionalExtraStopCharge | N | The charge for any additional stops. |
| OptionalExtraTimeCharge | N | The charge for each additional hour. |
Examples
XML Example Request
POST /concur/groundtransportation HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml
Content-Length: {length of content body}
<CC_LimoSearchRequest>
<ServiceType>110</ServiceType>
<ClassOfService>100</ClassOfService>
<PickupLocation>
<LocationType>100</LocationType>
<Airport>
<AirportCode />
</Airport>
<Address>209 Madison St., Suite 400</Address>
<City>Alexandria</City>
<State>VA</State>
<Country>US</Country>
<PostalCode>22314</PostalCode>
</PickupLocation>
<DropoffLocation>
<LocationType>200</LocationType>
<Airport>
<AirportCode>DCA</AirportCode>
</Airport>
<Address />
<City />
<State />
<Country />
<PostalCode />
</DropoffLocation>
<StartDateTime>2012-03-14T09:00</StartDateTime>
<EndDateTime />
<PickupInstructions />
<DropoffInstructions />
<LanguageCode>en-us</LanguageCode>
<Currency>USD</Currency>
<NumPassengers>1</NumPassengers>
<DiscountCode />
<VehicleType>100</VehicleType>
</CC_LimoSearchRequest>
XML Example of Successful Response
HTTPS/1.1 200 OK
Content-Type: application/xml
Content-Length: {length of content body}
<CC_LimoSearchReply size="1396" elaspedMs="782">
<Error>
<ErrorCode />
<ErrorSource />
<ErrorDescription />
</Error>
<RequestData>
<ServiceType>110</ServiceType>
<ClassOfService>100</ClassOfService>
<PickupLocation>
<Airport />
<Address>209 Madison St. #400</Address>
<City>Alexandria</City>
<State>VA</State>
<Country>US</Country>
<PostalCode>22314</PostalCode>
</PickupLocation>
<DropoffLocation>
<Airport>DCA</Airport>
<Address />
<City />
<State />
<Country />
<PostalCode />
</DropoffLocation>
<StartDateTime>2012-02-19T09:00:00</StartDateTime>
<EndDateTime />
<PickupInstructions />
<DropoffInstructions />
<Country>US</Country>
<NumPassengers>1</NumPassengers>
<VehicleType>100</VehicleType>
</RequestData>
<Limos>
<Limo>
<RateInfo>
<RateID>1</RateID>
<Rate>42.50</Rate>
<RateTypeCode>100</RateTypeCode>
<CategoryCode />
<MinHours />
<Currency>USD</Currency>
<NoRateText />
<DiscountType />
<BasePrice>35.00</BasePrice>
<ServiceCharge>5.00</ServiceCharge>
<SurChange desc="fuel">1.00</SurChange>
<Tax>1.50</Tax>
<ExtraPickupCharge />
<ExtraDropoffCharge />
<OptionalExtraStopCharge />
<OptionalExtraTimeCharge />
<Message>Ordinary Limo</Message>
</RateInfo>
<Vehicle>
<VehicleType>Sedan</VehicleType>
<Description>This is a Sedan.</Description>
<MaxPassengers>1</MaxPassengers>
<VehicleID>12</VehicleID>
</Vehicle>
<Vendor>
<VendorCode>LML</VendorCode>
<VendorName>LimoVendor</VendorName>
<PhoneNumber>4354654654</PhoneNumber>
</Vendor>
<AcceptedFops>
<FormOfPayment>
<CreditCard>
<Type>VI</Type>
</CreditCard>
</FormOfPayment>
</AcceptedFops>
</Limo>
</Limos>
</CC_LimoSearchReply>
Direct Connect - Ground Transportation - Post a transportation search
A post transportation search request is sent when the Travel user searches for ground transportation.
Request
URI
The Ground Transportation direct connect sends the relevant information to a URI that the travel supplier maintains. The standard location is:
https://{servername}/concur/groundtransportation
The URI is configured by the supplier when registering the partner application.
Headers
Accept Header
application/xml
Authorization Header
Authorization header with OAuth credentials.
Request Body
The request will contain a CC_LimoSearchRequest parent element, containing the following child elements.
ServiceType: The type of service requested. Will contain one of the following values:
100: Point to point
110: One way to airport
111: One way from airport
120: One way to train station
121: One way from train station
200: Hourly
300: Airport to airport
ClassOfService: The requested service class. Will contain one of the following values:
100: Normal
200: High
300: Highest
If this value is not provided by the user, it will default to 100.
PickupLocation: The pick up location. This parent element contains the following child elements:
PickupLocation Elements
| Element | Description |
|---|---|
| LocationType | One of the following: 100 - Address, 200 - Airport, 300 - Train station. |
| Airport | Refer to the Airport Elements table. Provided if the LocationType = 200. |
| TrainStation | Refer to the Train Station Elements table. Provided if the LocationType = 300. |
| Address | The street address of the location. Provided if the LocationType = 100. |
| City | The location city. |
| State | The location state. Preferably 2 characters, max 10 characters. |
| Country | The location's 2 character ISO 3166-1 alpha-2 country code. Example: US |
| PostalCode | The location postal code. |
| ExtraNotes | Additional notes about the location. Example: Ring doorbell, Holiday Inn, etc. |
DropoffLocation: The drop off location. This parent element contains the following child elements:
DropoffLocation Elements
| Element | Description |
|---|---|
| LocationType | One of the following: 100 - Address, 200 - Airport, 300 - Train station. |
| Airport | Refer to the Airport Elements table. Provided if the LocationType = 200. |
| TrainStation | Refer to the Train Station Elements table. Provided if the LocationType = 300. |
| Address | The street address of the location. Provided if the LocationType = 100. |
| City | The location city. |
| State | The location state. Preferably 2 characters, max 10 characters. |
| Country | The location's 2 character ISO 3166-1 alpha-2 country code. Example: US |
| PostalCode | The location postal code. |
| ExtraNotes | Additional notes about the location. Example: Apartment building, gravel driveway, etc. |
StartDateTime: The time, in GMT, that the reservation must begin. Format: 2015-05-19T18:00:00
EndDateTime: The time, in GMT that the reservation will end. Provided for hourly reservations. Format: 2015-05-19T18:00:00
PickupInstructions: Additional instructions about the pick up request.
DropoffInstructions: Additional instructions about the drop off request.
LanguageCode: The language of the traveler. Will be one of the following options:
en: English
en-us: English (US)
en-gb: English (UK)
fr: French
fr-ca: French (Canadian)
de: German
pt: Portuguese
es: Spanish
nl: Dutch
it: Italian
ja: Japanese
pl: Polish
pt-br: Portuguese (Brazilian)
ru: Russian
hu: Hungarian
ko: Korean
sv: Swedish
zh-cn: Chinese
zh-tw: Traditional Chinese
Currency: The 3-letter ISO 4217 currency code for the reservation amount.
NumPassengers: The number of passengers.
VehicleType: The type of vehicle requested. Will be one of the following options:
100: Sedan
200: Limo
201: Stretch Limo
300: SUV
301: Stretch SUV
400: Van
401: Mini-Bus
402: Bus
500: Motor Coach
501: Antique/Classic
502: Trolley
503: Carriage
600: Shuttle
900: Any
DiscountCode: The discount code information. This parent element contains the following child elements:
DiscountCode Elements
| Element | Description |
|---|---|
| CorporateID | The user's corporate ID. |
| VendorCode | The user's vendor code. |
| DiscountNumber | The user's discount number. |
Airport Elements
AirportCode: The IATA Code for the airport.
Flight: The flight information. This parent element contains the following child elements:
Flight Elements
| Element | Description |
|---|---|
| CarrierCode | The airline code. |
| FlightNumber | The flight number. |
| ArrivalDateTime | The flight arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00 |
| DepartureDateTime | The flight departure time. Only provided for the DropoffLocation element. Format: 2015-05-19T18:00:00 |
Train Station Elements
| Element | Description |
|---|---|
| StationCode | The station code. |
| StationName | The name of the station. |
| City | The city the station is located in. |
| State | The state the station is located in. Preferably 2 characters, max 10 characters. |
| Train | The train information. This parent element contains the following child elements. |
Train Elements
| Element | Description |
|---|---|
| CarrierCode | The code of the train carrier. |
| CarrierName | The name of the train carrier. |
| TrainNumber | The train number. |
| ArrivalDateTime | The train arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00 |
| DepartureDateTime | The train departure time. Only provided for the DropoffLocation element. Format: 2015-05-19T18:00:00 |
Response
The supplier responds to the Limo Search request by returning the details of an available reservation that matches the search criteria.
Content Types
application/xml
Content Body
The response will include a CC_LimoSearchReply parent element, with the following child elements:
Error: The error information, if an error occurred. Required. This parent element contains the following child elements:
Error Elements
| Element | Description |
|---|---|
| ErrorCode | The code for the error. Will contain one of the following values: 100: Pickup/dropoff location related error 200: Pickup/dropoff time related error 300: Other request parameters related error 400: Credential related error 500: No rate/service available 900: Unknown error |
| ErrorSource | The source of the error. |
| ErrorDescription | The additional error information. |
RequestData: This parent element contains a copy of the original request data. Only the ServiceType, PickupLocation, DropoffLocation, and StartDateTime elements are required.
Limos: This parent element contains a Limo child element with the available reservation information. Refer to the Limo Elements table for the details of the child elements of the Limo element.
Limo Elements
RateInfo: The rate information for the limo. Refer to the Rate Information Elements table for more information. Required.
Vehicle: The type of vehicle. Required. This parent element contains the following child elements:
VehicleType: One of the following values:
100: Sedan
200: Limo
250: Stretch Limo
300: SUV
350: Stretch SUV
400: Van
450: Mini-Bus
500: Motor Coach
600: Shuttle
700: Trolley
800: Carriage
900: Any
Description: The detailed description of the vehicle.
MaxPassengers: The maximum number of passengers allowed in the vehicle. Must be greater than zero.
VehicleID: Information to identify the specific vehicle.
Vendor: The reservation vendor. Required. This parent element contains the following child elements:
Vendor Elements
| Element | Description |
|---|---|
| VendorCode | The vendor code for the vendor. |
| VendorName | The vendor's name. |
| PhoneNumber | The vendor's phone number. |
AcceptedFops: The accepted forms of payment. Required. This parent element contains the FormOfPayment child element. The FormOfPayment element contains the allowed forms of payment. The possible child elements are:
FormOfPayment Elements
| Element | Description |
|---|---|
| CreditCard | This element will appear if the Credit Card form of payment is accepted. Contains the Type child element with one of the following values: AX - American Express, CA - Master Card, VI - Visa, DS - Discover Card, DC - Diners Club |
| Cash | This element will appear if the Cash form of payment is accepted. |
| Check | This element will appear if the Check form of payment is accepted. |
| DirectBilling | This element will appear if the Direct Billing form of payment is accepted. |
Rate Information Elements
| Element | Required? | Description |
|---|---|---|
| RateID | Y | The rate identifier. |
| Rate | Y | The BasePrice + ServiceCharge + SurCharge + Tax |
| RateTypeCode | Y | The code for the rate type. Will be one of the following options: F: Flat rate H: Hourly E: Estimated amount N: Currently not available |
| CategoryCode | N | Extra information that will be passed back during sell request to help identify the rate. |
| Currency | Y | The 3-letter ISO 4217 currency code for the rate amount. |
| NoRateText | N | Explanation of rate type. Provided if RateTypeCode = N |
| MinHours | N | The minimum number of hours for the reservation. |
| DiscountType | N | The type of discount applied. |
| BasePrice | N | The reservation price without taxes, surcharges or service charges. |
| ServiceCharge | N | The service charge for the reservation. |
| SurCharge | N | This element contains the desc attribute, with text describing the reason for the surcharge. Example: <SurCharge desc="fuel"> |
| Tax | N | The reservation tax. |
| ExtraPickupCharge | N | Any additional fees for the pickup service. |
| ExtraDropoffCharge | N | Any additional fees for the drop off service. |
| OptionalExtraStopCharge | N | The charge for any additional stops. |
| OptionalExtraTimeCharge | N | The charge for each additional hour. |
Examples
XML Example Request
POST /concur/groundtransportation HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml
Content-Length: {length of content body}
<CC_LimoSearchRequest>
<ServiceType>110</ServiceType>
<ClassOfService>100</ClassOfService>
<PickupLocation>
<LocationType>100</LocationType>
<Airport>
<AirportCode />
</Airport>
<Address>209 Madison St., Suite 400</Address>
<City>Alexandria</City>
<State>VA</State>
<Country>US</Country>
<PostalCode>22314</PostalCode>
</PickupLocation>
<DropoffLocation>
<LocationType>200</LocationType>
<Airport>
<AirportCode>DCA</AirportCode>
</Airport>
<Address />
<City />
<State />
<Country />
<PostalCode />
</DropoffLocation>
<StartDateTime>2012-03-14T09:00</StartDateTime>
<EndDateTime />
<PickupInstructions />
<DropoffInstructions />
<LanguageCode>en-us</LanguageCode>
<Currency>USD</Currency>
<NumPassengers>1</NumPassengers>
<DiscountCode />
<VehicleType>100</VehicleType>
</CC_LimoSearchRequest>
XML Example of Successful Response
HTTPS/1.1 200 OK
Content-Type: application/xml
Content-Length: {length of content body}
<CC_LimoSearchReply size="1396" elaspedMs="782">
<Error>
<ErrorCode />
<ErrorSource />
<ErrorDescription />
</Error>
<RequestData>
<ServiceType>110</ServiceType>
<ClassOfService>100</ClassOfService>
<PickupLocation>
<Airport />
<Address>209 Madison St. #400</Address>
<City>Alexandria</City>
<State>VA</State>
<Country>US</Country>
<PostalCode>22314</PostalCode>
</PickupLocation>
<DropoffLocation>
<Airport>DCA</Airport>
<Address />
<City />
<State />
<Country />
<PostalCode />
</DropoffLocation>
<StartDateTime>2012-02-19T09:00:00</StartDateTime>
<EndDateTime />
<PickupInstructions />
<DropoffInstructions />
<Country>US</Country>
<NumPassengers>1</NumPassengers>
<VehicleType>100</VehicleType>
</RequestData>
<Limos>
<Limo>
<RateInfo>
<RateID>1</RateID>
<Rate>42.50</Rate>
<RateTypeCode>100</RateTypeCode>
<CategoryCode />
<MinHours />
<Currency>USD</Currency>
<NoRateText />
<DiscountType />
<BasePrice>35.00</BasePrice>
<ServiceCharge>5.00</ServiceCharge>
<SurChange desc="fuel">1.00</SurChange>
<Tax>1.50</Tax>
<ExtraPickupCharge />
<ExtraDropoffCharge />
<OptionalExtraStopCharge />
<OptionalExtraTimeCharge />
<Message>Ordinary Limo</Message>
</RateInfo>
<Vehicle>
<VehicleType>Sedan</VehicleType>
<Description>This is a Sedan.</Description>
<MaxPassengers>1</MaxPassengers>
<VehicleID>12</VehicleID>
</Vehicle>
<Vendor>
<VendorCode>LML</VendorCode>
<VendorName>LimoVendor</VendorName>
<PhoneNumber>4354654654</PhoneNumber>
</Vendor>
<AcceptedFops>
<FormOfPayment>
<CreditCard>
<Type>VI</Type>
</CreditCard>
</FormOfPayment>
</AcceptedFops>
</Limo>
</Limos>
</CC_LimoSearchReply>
Direct Connect - Ground Transportation - Update reservation with supplier
This request is sent when the Travel user updates an existing ground transportation reservation.
Request
URI
The Ground Transportation direct connect sends the relevant information to a URI that the travel supplier maintains. The standard location is:
https://{servername}/concur/groundtransportation
The URI is configured by the supplier when registering the partner application.
Headers
Accept Header
application/xml
Authorization Header
Authentication header with Base64 encoded basic authentication credentials (login ID and password) is required. The basic authentication credentials are established during the application review process.
Authorization: Basic {Base64 encoded LoginID:Password}
Request Body
The request will contain a CC_LimoUpdateRequest parent element, containing the following child elements:
| Element | Required? | Description |
|---|---|---|
| ReservationID | The unique identifier for the reservation. | |
| CorporateClient | The corporate client the booking is on behalf of. This parent element contains a CompanyCode child element containing the code for the company of the client. | |
| Booker | The user booking the reservation. For information about the child elements of this parent element, see the Booker elements table below. | |
| PrimaryPassenger | The passenger contact name for the reservation. For information about the child elements of this parent element, see the PrimaryPassenger elements table below. | |
| ServiceType | The type of service requested. Will contain one of the following values: 100: Point to point 110: One way to airport 111: One way from airport 120: One way to train station 121: One way from train station 200: Hourly 300: Airport to airport |
|
| ClassOfService | The requested service class. Will contain one of the following values: 100: Normal 200: High 300: Highest If this value is not provided by the user, it will default to 100. |
|
| PickupLocation | The pick up location. For information about the child elements of this parent element, see the PickupLocation elements table below. | |
| DropoffLocation | The drop off location. For information about the child elements of this parent element, see the DropoffLocation elements table below. | |
| StartDateTime | The time, in GMT, that the reservation must begin. Format: 2015-05-19T18:00:00 | |
| EndDateTime | The time, in GMT that the reservation will end. Provided for hourly reservations. Format: 2015-05-19T18:00:00 | |
| PickupInstructions | Additional instructions about the pick up request. | |
| DropoffInstructions | Additional instructions about the drop off request. | |
| LanguageCode | The language of the traveler. Will be one of the following options: en: English en-us: English (US) en-gb: English (UK) fr: French fr-ca: French (Canadian) de: German pt: Portuguese es: Spanish nl: Dutch it: Italian ja: Japanese pl: Polish pt-br: Portuguese (Brazilian) ru: Russian hu: Hungarian ko: Korean sv: Swedish zh-cn: Chinese zh-tw: Traditional Chinese |
|
| Currency | The 3-letter ISO 4217 currency code for the reservation amount. | |
| NumPassengers | The number of passengers. | |
| DiscountCode | The discount code information. For information about the child elements of this parent element, see the DiscountCode elements table below. | |
| FormOfPayment | The form of payment for the reservation. For information about the child elements of this parent element, see the FormOfPayment elements table below. | |
| AccountingInfo | The accounting information for the reservation. This parent element contains one or more AccountingField elements: AccountingField1 through AccountingField5. These fields contain detailed accounting information. | |
| RequestedDriver | The name of the requested driver, if available. | |
| SpecialServiceRequest | The details of the special service request, if available. | |
| PickupServiceArrangement | The details of the pickup arrangement, if available. | |
| DropoffServiceArrangement | The details of the dropoff arrangement, if available. | |
| ExtraStopArrangement | The details of the extra stop arrangement, if available. |
Booker Elements
| Element | Description |
|---|---|
| UserID | The user's SAP Concur user ID. |
| EmailAddress | The user's email address. |
| Phone | The user's contact number. |
PrimaryPassenger Elements
| Element | Description |
|---|---|
| FirstName | The contact's first name. |
| LastName | The contact's last name. |
| Phone | The contact's phone number. |
| Phone2 | The contact's backup phone number. |
| CellPhone | The contact's cell phone number. |
| EmailAddress | The contact's email address. |
PickupLocation Elements
| Element | Description |
|---|---|
| LocationType | One of the following: 100 - Address, 200 - Airport, 300 - Train station. |
| Airport | Refer to the Airport elements table. Provided if the LocationType = 200. |
| TrainStation | Refer to the Train Station elements table. Provided if the LocationType = 300. |
| Address | The street address of the location. Provided if the LocationType = 100. |
| City | The location city. |
| State | The location state. Preferably 2 characters, max 10 characters. |
| Country | The location's 2 character ISO 3166-1 alpha-2 country code. Example: US |
| PostalCode | The location postal code. |
| ExtraNotes | Additional notes about the location. Example: Ring doorbell, Holiday Inn, etc. |
DropoffLocation Elements
| Element | Description |
|---|---|
| LocationType | One of the following: 100 - Address, 200 - Airport, 300 - Train station, 400 - As directed. |
| Airport | Refer to the Airport elements table. Provided if the LocationType = 200. |
| TrainStation | Refer to the Train Station elements table. Provided if the LocationType = 300. |
| Address | The street address of the location. Provided if the LocationType = 100. |
| City | The location city. |
| State | The location state. Preferably 2 characters, max 10 characters. |
| Country | The location's 2 character ISO 3166-1 alpha-2 country code. Example: US |
| PostalCode | The location postal code. |
| ExtraNotes | Additional notes about the location. Example: Apartment Building, gravel driveway, etc. |
DiscountCode Elements
| Element Name | Description |
|---|---|
| CorporateID | The user's corporate ID. |
| VendorCode | The user's vendor code. |
| DiscountNumber | The user's discount number. |
FormOfPayment Elements
| Element | Description |
|---|---|
| CreditCard | If present, the passenger will pay with credit card. Refer to the Credit Card Elements table for the child elements. |
| Cash | If present, the passenger will pay cash. |
| Check | If present, the passenger will pay with a check. |
| DirectBilling | If present, the passenger will pay through direct billing. |
Airport Elements
| Element Name | Description |
|---|---|
| AirportCode | The IATA code for the airport. |
| Flight | The flight information. For information about the child elements of this parent element, see the Flight elements table below. |
Flight Elements
| Element Name | Description |
|---|---|
| CarrierCode | The airline code. |
| FlightNumber | The flight number. |
| ArrivalDateTime | The flight arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00 |
| DepartureDateTime | The flight departure time. Only provided for the DropoffLocation element. Format: 2015-05-19T18:00:00 |
Train Station Elements
| Element Name | Required/Optional | Data Type | Description |
|---|---|---|---|
| StationCode | The station code. | ||
| StationName | The name of the station. | ||
| City | The city the station is located in. | ||
| State | The state the station is located in. Preferably 2 characters, max 10 characters. | ||
| Train | The train information. For information about the child elements of this parent element, see the Train elements table below. |
Train Elements
| Element Name | Description |
|---|---|
| CarrierCode | The code of the train carrier. |
| CarrierName | The name of the train carrier. |
| TrainNumber | The train number. |
| ArrivalDateTime | The train arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00 |
| DepartureDateTime | The train departure time. Only provided for the DropoffLocation element. Format: 2015-05-19T18:00:00 |
Credit Card Elements
| Element Name | Description |
|---|---|
| Type | The card type. |
| Number | The card number. |
| Expiration | The card expiration date. Format: 2013-02-19 |
| Name | The name on the card. |
| Address | The street information of the billing address of the car. |
| City | The city of the billing address of the car. |
| State | The state of the billing address of the car. |
| Country | The country of the billing address of the car. |
| PostalCode | The postal code of the billing address of the car. |
Response
The supplier responds to the update request with the reservation details.
Content Types
application/xml
Response Schema
The response will include a CC_LimoUpdateReply parent element, with the following child elements:
| Element | Required? | Description |
|---|---|---|
| Error | Y | The error information, if an error occurred. For information about the child elements of this parent element, see the Error elements table below. |
| ReservationID | N | The identifier for the reservation. |
| Status | N | The status of the reservation. The value will be one of the following: RB: Reservation Booked RA: Reservation Accepted RD: Reservation Declined CB: Change Booked CA: Change Accepted CD: Change Declined XB: Cancellation Requested XA: Cancellation Accepted XD: Cancellation Declined RC: Reservation Closed |
| ConfNum | N | The confirmation number for the reservation. |
| CancelPolicy | N | The cancellation policy for the reservation. |
| CancelNum | N | The cancellation number for the reservation. |
| PrimaryPassenger | Y | The passenger contact name for the reservation. For information about the child elements of this parent element, see the PrimaryPassenger elements table above. |
| ServiceType | Y | The type of service requested. Will contain one of the following values: 100: Point to point 110: One way to airport 111: One way from airport 120: One way to train station 121: One way from train station 200: Hourly 300: Airport to airport |
| ClassOfService | N | The requested service class. Will contain one of the following values: 100: Normal 200: High 300: Highest If this value is not provided by the user, it will default to 100. |
| PickupLocation | Y | The pick up location. For information about the child elements of this parent element, see the PickupLocation elements table above. |
| DropoffLocation | Y | The drop off location. For information about the child elements of this parent element, see the DropoffLocation elements table above. |
| StartDateTime | Y | The time, in GMT, that the reservation must begin. Format: 2015-05-19T18:00:00 |
| EndDateTime | N | The time, in GMT that the reservation will end. Provided for hourly reservations. Format: 2015-05-19T18:00:00 |
| PickupInstructions | N | Additional instructions about the pick up request. |
| DropoffInstructions | N | Additional instructions about the drop off request. |
| LanguageCode | Y | The language of the traveler. Will be one of the following options: en: English en-us: English (US) en-gb: English (UK) fr: French fr-ca: French (Canadian) de: German pt: Portuguese es: Spanish nl: Dutch it: Italian ja: Japanese pl: Polish pt-br: Portuguese (Brazilian) ru: Russian hu: Hungarian ko: Korean sv: Swedish zh-cn: Chinese zh-tw: Traditional Chinese |
| Currency | Y | The 3-letter ISO 4217 currency code for the reservation amount. |
| NumPassengers | N | The number of passengers. |
| RequestedDriver | N | The name of the requested driver, if available. |
| SpecialServiceRequest | N | The details of the special service request, if available. |
| PickupServiceArrangement | N | The details of the pickup arrangement, if available. |
| DropoffServiceArrangement | N | The details of the dropoff arrangement, if available. |
| ExtraStopArrangement | N | The details of the extra stop arrangement, if available. |
| RateInfo | Y | The booked rate details. Refer to the Rate Information elements table below for more information. |
| Vehicle | Y | The vehicle details. For information about the child elements of this parent element, see the Vehicle elements table below. |
| Vendor | Y | The reservation vendor. For information about the child elements of this parent element, see the Vendor elements table below. |
| FormOfPayment | Y | The form of payment for the reservation. For information about the child elements of this parent element, see the FormOfPayment elements table below. |
| RateDisclaimer | N | Disclaimer text about the rate. |
| ProviderFeedback | N | Any additional feedback from the supplier. |
| AccountingInfo | N | The accounting information for the reservation. This parent element contains one or more AccountingField elements: AccountingField1 through AccountingField5. These fields contain detailed accounting information. |
Error Elements
| Element | Description |
|---|---|
| ErrorCode | The code for the error. Will contain one of the following values: 100: Pickup/dropoff location related error 200: Pickup/dropoff time related error 300: Other request parameters related error 400: Credential related error 500: No rate/service available 600: FOP related error 900: Unknown error |
| ErrorSource | The source of the error. |
| ErrorDescription | The additional error information. |
Vehicle Elements
| Element | Description |
|---|---|
| VehicleType | One of the following values: 100: Sedan 200: Limo 250: Stretch Limo 300: SUV 350: Stretch SUV 400: Van 450: Mini-Bus 500: Motor Coach 600: Shuttle 700: Trolley 800: Carriage 900: Any |
| Description | The vehicle description. |
| MaxPassengers | The maximum number of passengers for the car. Must be greater than zero. |
| VehicleID | Information to identify the specific vehicle. |
Rate Information Elements
| Element Name | Required? | Data Type | Description |
|---|---|---|---|
| RateID | Y | The rate identifier. | |
| Rate | Y | The BasePrice + ServiceCharge + SurCharge + Tax | |
| RateTypeCode | Y | The code for the rate type. Will be one of the following options: F: Flat rate H: Hourly E: Estimated amount N: Currently not available |
|
| CategoryCode | N | Extra information that will be passed back during sell request to help identify the rate. | |
| Currency | Y | The 3-letter ISO 4217 currency code for the rate amount. | |
| NoRateText | N | Explanation of rate type. Provided if RateTypeCode = N | |
| MinHours | N | The minimum number of hours for the reservation. | |
| DiscountType | N | The type of discount applied. | |
| BasePrice | N | The reservation price without taxes, surcharges or service charges. | |
| ServiceCharge | N | The service charge for the reservation. | |
| SurCharge | N | This element contains the desc attribute, with text describing the reason for the surcharge. Example: <SurCharge desc="fuel"> |
|
| Tax | N | The reservation tax. | |
| ExtraPickupCharge | N | Any additional fees for the pickup service. | |
| ExtraDropoffCharge | N | Any additional fees for the drop off service. | |
| OptionalExtraStopCharge | N | The charge for any additional stops. | |
| OptionalExtraTimeCharge | N | The charge for each additional hour. |
Vendor Elements
| Element | Description |
|---|---|
| VendorCode | The vendor code for the vendor. |
| VendorName | The vendor's name. |
| PhoneNumber | The vendor's phone number. |
FormOfPayment Elements
| Element | Description |
|---|---|
| CreditCard | If present, the passenger will pay with credit card. Refer to the Reply Credit Card elements table for the child elements. |
| Cash | If present, the passenger will pay cash. |
| Check | If present, the passenger will pay with a check. |
| DirectBilling | If present, the passenger will pay through direct billing. |
Airport Elements
| Element Name | Description |
|---|---|
| AirportCode | The IATA code for the airport. |
| Flight | The flight information. For information about the child elements of this parent element, see the Flight elements table below. |
Flight Elements
| Element Name | Description |
|---|---|
| CarrierCode | The airline code. |
| FlightNumber | The flight number. |
| ArrivalDateTime | The flight arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00 |
| DepartureDateTime | The flight departure time. Only provided for the DropoffLocation element. Format: 2015-05-19T18:00:00 |
Train Station Elements
| Element Name | Required/Optional | Data Type | Description |
|---|---|---|---|
| StationCode | The station code. | ||
| StationName | The name of the station. | ||
| City | The city the station is located in. | ||
| State | The state the station is located in. Preferably 2 characters, max 10 characters. | ||
| Train | The train information. For information about the child elements of this parent element, see the Train elements table below. |
Train Elements
| Element Name | Description |
|---|---|
| CarrierCode | The code of the train carrier. |
| CarrierName | The name of the train carrier. |
| TrainNumber | The train number. |
| ArrivalDateTime | The train arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00 |
| DepartureDateTime | The train departure time. Only provided for the DropoffLocation element. Format: 2015-05-19T18:00:00 |
Reply Credit Card Elements
| Element Name | Required? | Description |
|---|---|---|
| Type | The card type. | |
| Number | The card number. | |
| Expiration | The card expiration date. Format: 2013-02-19 |
Examples
XML Example Request
POST /concur/groundtransportation HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml
Content-Length: {length of content body}
<CC_LimoUpdateRequest>
<ReservationID>1234</ReservationID>
<CorporateClient>
<CompanyCode>339</CompanyCode>
</CorporateClient>
<Booker>
<UserID>55414</UserID>
<EmailAddress>cmiller@example.com</EmailAddress>
<Phone>5551234567</Phone>
</Booker>
<PrimaryPassenger>
<FirstName>Chris</FirstName>
<LastName>Miller</LastName>
<Phone>5551234567</Phone>
<Phone2>5551234568</Phone2>
<CellPhone>5551234555</CellPhone>
<EmailAddress>cmiller@example.com</EmailAddress>
</PrimaryPassenger>
<ServiceType>110</ServiceType>
<ClassOfService />
<PickupLocation>
<LocationType>100</LocationType>
<Airport>
<AirportCode />
<Flight>
<CarrierCode />
<FlightNumber />
<ArrivalDateTime />
</Flight>
</Airport>
<TrainStation>
<StationCode />
<StationName />
<City />
<State />
<Train>
<CarrierCode />
<CarrierName />
<TrainNumber />
<ArrivalDateTime />
</Train>
</TrainStation>
<Address>209 Madison St</Address>
<City>Alexandria</City>
<State>VA</State>
<Country>US</Country>
<PostalCode>22314</PostalCode>
<ExtraNotes />
</PickupLocation>
<DropoffLocation>
<LocationType>200</LocationType>
<Airport>
<AirportCode>DCA</AirportCode>
<Flight>
<CarrierCode>UA</CarrierCode>
<FlightNumber>333</FlightNumber>
<DepartureDateTime>2012-02-19T11:29:00</DepartureDateTime>
</Flight>
</Airport>
<TrainStation>
<StationCode />
<StationName />
<City />
<State />
<Train>
<CarrierCode />
<CarrierName />
<TrainNumber />
<DepartureDateTime />
</Train>
</TrainStation>
<Address />
<City />
<State />
<Country />
<PostalCode />
<ExtraNotes />
</DropoffLocation>
<StartDateTime>2012-02-19T09:00:00</StartDateTime>
<EndDateTime />
<PickupInstructions>pick me up</PickupInstructions>
<DropoffInstructions>None</DropoffInstructions>
<LanguageCode>en-us</LanguageCode>
<Currency>USD</Currency>
<NumPassengers>1</NumPassengers>
<DiscountCode>
<CorporateID />
<VendorCode />
<DiscountNumber />
</DiscountCode>
<FormOfPayment>
<Cash />
<Check />
<DirectBilling />
<CreditCard>
<Type>VI</Type>
<Number>XXXXXXXXXXXX1111</Number>
<Expiration>2013-02-19</Expiration>
</CreditCard>
</FormOfPayment>
<AccountingInfo>
<AccountingField1>715</AccountingField1>
<AccountingField2>temp@outtask.com</AccountingField2>
<AccountingField3>11</AccountingField3>
<AccountingField4>Development</AccountingField4>
<AccountingField5/>
</AccountingInfo>
<RequestedDriver />
<SpecialServiceRequest />
<PickupServiceArrangement />
<DropoffServiceArrangement />
<ExtraStopArrangement />
</CC_LimoUpdateRequest>
XML Example of Successful Response
HTTPS/1.1 200 OK
Content-Type: application/xml
Content-Length: {length of content body}
<CC_LimoUpdateReply>
<Error>
<ErrorCode />
<ErrorSource />
<ErrorDescription />
</Error>
<ReservationID>1234</ReservationID>
<Status>RB</Status>
<ConfNum/>
<CancelPolicy />
<CancelNum/>
<PrimaryPassenger>
<FirstName>Chris</FirstName>
<LastName>Miller</LastName>
<Phone>5551234567</Phone>
<Phone2>5551234568</Phone2>
<CellPhone>5551234555</CellPhone>
<EmailAddress>cmiller@example.com</EmailAddress>
</PrimaryPassenger>
<ServiceType>110</ServiceType>
<ClassOfService />
<PickupLocation>
<LocationType>100</LocationType>
<Airport>
<AirportCode />
<Flight>
<CarrierCode />
<FlightNumber />
<ArrivalDateTime />
</Flight>
</Airport>
<TrainStation>
<StationCode />
<StationName />
<City />
<State />
<Train>
<CarrierCode />
<CarrierName />
<TrainNumber />
</Train>
</TrainStation>
<Address>209 Madison St #400</Address>
<City>Alexandria</City>
<State>VA</State>
<Country>US</Country>
<PostalCode>22314</PostalCode>
<ExtraNotes />
</PickupLocation>
<DropoffLocation>
<LocationType>200</LocationType>
<Airport>
<AirportCode>DCA</AirportCode>
<Flight>
<CarrierCode>UA</CarrierCode>
<FlightNumber>333</FlightNumber>
<DepartureDateTime>2012-02-19T11:29:00</DepartureDateTime>
</Flight>
</Airport>
<TrainStation>
<StationCode />
<StationName />
<City />
<State />
<Train>
<CarrierCode />
<CarrierName />
<TrainNumber />
<DepartureDateTime />
</Train>
</TrainStation>
<Address />
<City />
<State />
<Country />
<PostalCode />
<ExtraNotes />
</DropoffLocation>
<StartDateTime>2012-02-19T09:00:00</StartDateTime>
<EndDateTime />
<PickupInstructions>pick me up</PickupInstructions>
<DropoffInstructions>None</DropoffInstructions>
<LanguageCode>en-us</LanguageCode>
<Currency>USD</Currency>
<NumPassengers>1</NumPassengers>
<RequestedDriver />
<SpecialServiceRequest />
<PickupServiceArrangement />
<DropoffServiceArrangement />
<ExtraStopArrangement />
<RateInfo>
<RateID>5</RateID>
<Rate>42.50</Rate>
<RateTypeCode>E</RateTypeCode>
<CategoryCode />
<MinHours />
<Currency>US</Currency>
<NoRateText />
<DiscountType />
<BasePrice>35.00</BasePrice>
<ServiceCharge>5.00</ServiceCharge>
<SurCharge desc="fuel">1.00</SurCharge>
<Tax>1.50</Tax>
<ExtraPickupCharge />
<ExtraDropoffCharge />
<OptionalExtraStopCharge />
<OptionalExtraTimeCharge />
<Message />
</RateInfo>
<RateDisclaimer />
<Vehicle>
<VehicleType>100</VehicleType>
<Description>This is a Sedan.</Description>
<MaxPassengers>1</MaxPassengers>
<VehicleID>12</VehicleID>
</Vehicle>
<Vendor>
<VendorCode>LML</VendorCode>
<VendorName>LimoVendor</VendorName>
<PhoneNumber>4354654654</PhoneNumber>
</Vendor>
<ProviderFeedback />
<FormOfPayment>
<Cash />
<Check />
<DirectBilling />
<CreditCard>
<Type>VI</Type>
<Number>XXXXXXXXXXXX1111</Number>
<Expiration>2013-02-19</Expiration>
</CreditCard>
</FormOfPayment>
<AccountingInfo>
<AccountingField1>715</AccountingField1>
<AccountingField2>temp@outtask.com</AccountingField2>
<AccountingField3>11</AccountingField3>
<AccountingField4>Development</AccountingField4>
<AccountingField5/>
</AccountingInfo>
</CC_LimoUpdateReply>
Direct Connect - Ground Transportation - Update reservation with Travel
This API has been deprecated.
Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.
Learn more in the API Lifecycle & Deprecation Policy.
This request is sent when the ground transportation service provider needs to send an update to the reservation to Travel.
Request
URI
https://app2.outtask.com/api/tws/v1.0/Limo/PostBack
Headers
Accept Header
application/xml
Authorization Header
Authorization header with OAuth credentials. Required. Refer to the OAuth documentation for more information.
Authorization: OAuth {OAuth access token associated with the account making the call with Web Services Administrator role}
Request Body
The request will contain a CC_LimoPostBackRequest parent element, containing the following child elements:
| Element | Required? | Description |
|---|---|---|
| Error | Y | The error information, if an error occurred. For information about the child elements of this parent element, see the Error elements table below. |
| ReservationID | N | The identifier for the reservation. |
| Status | N | The status of the reservation. The value will be one of the following: RB: Reservation Booked RA: Reservation Accepted RD: Reservation Declined CB: Change Booked CA: Change Accepted CD: Change Declined XB: Cancellation Requested XA: Cancellation Accepted XD: Cancellation Declined RC: Reservation Closed |
| ConfNum | N | The confirmation number for the reservation. |
| CancelPolicy | N | The cancellation policy for the reservation. |
| CancelNum | N | The cancellation number for the reservation. |
| PrimaryPassenger | Y | The passenger contact name for the reservation. For information about the child elements of this parent element, see the PrimaryPassenger elements table below. |
| ServiceType | Y | The type of service requested. Will contain one of the following values: 100: Point to point 110: One way to airport 111: One way from airport 120: One way to train station 121: One way from train station 200: Hourly 300: Airport to airport |
| ClassOfService | N | The requested service class. Will contain one of the following values: 100: Normal 200: High 300: Highest If this value is not provided by the user, it will default to 100. |
| PickupLocation | Y | The pick up location. For information about the child elements of this parent element, see the PickupLocation elements table below. |
| DropoffLocation | Y | The drop off location. For information about the child elements of this parent element, see the DropoffLocation elements table below. |
| StartDateTime | Y | The time, in GMT, that the reservation must begin. Format: 2015-05-19T18:00:00 |
| EndDateTime | N | The time, in GMT that the reservation will end. Provided for hourly reservations. Format: 2015-05-19T18:00:00 |
| PickupInstructions | N | Additional instructions about the pick up request. |
| DropoffInstructions | N | Additional instructions about the drop off request. |
| LanguageCode | Y | The language of the traveler. Will be one of the following options: en: English en-us: English (US) en-gb: English (UK) fr: French fr-ca: French (Canadian) de: German pt: Portuguese es: Spanish nl: Dutch it: Italian ja: Japanese pl: Polish pt-br: Portuguese (Brazilian) ru: Russian hu: Hungarian ko: Korean sv: Swedish zh-cn: Chinese zh-tw: Traditional Chinese |
| Currency | Y | The 3-letter ISO 4217 currency code for the reservation amount. |
| NumPassengers | N | The number of passengers. |
| RequestedDriver | N | The name of the requested driver, if available. |
| SpecialServiceRequest | N | The details of the special service request, if available. |
| PickupServiceArrangement | N | The details of the pickup arrangement, if available. |
| DropoffServiceArrangement | N | The details of the dropoff arrangement, if available. |
| ExtraStopArrangement | N | The details of the extra stop arrangement, if available. |
| RateInfo | Y | The booked rate details. Refer to the Rate Information elements table for more information. |
| Vehicle | Y | The vehicle details. For information about the child elements of this parent element, see the Vehicle elements table below. |
| Vendor | Y | The reservation vendor. For information about the child elements of this parent element, see the Vendor elements table below. |
| FormOfPayment | Y | The form of payment for the reservation. For information about the child elements of this parent element, see the FormOfPayment elements table below. |
| RateDisclaimer | N | Disclaimer text about the rate. |
| ProviderFeedback | N | Any additional feedback from the supplier. |
| AccountingInfo | N | The accounting information for the reservation. This parent element contains one or more AccountingField elements: AccountingField1 through AccountingField5. These fields contain detailed accounting information. |
Error Elements
| Element | Description |
|---|---|
| ErrorCode | The code for the error. Will contain one of the following values: 100: Pickup/dropoff location related error 200: Pickup/dropoff time related error 300: Other request parameters related error 400: Credential related error 500: No rate/service available 600: FOP related error 900: Unknown error |
| ErrorSource | The source of the error. |
| ErrorDescription | The additional error information. |
PrimaryPassenger Elements
| Element | Description |
|---|---|
| FirstName | The contact's first name. |
| LastName | The contact's last name. |
| Phone | The contact's phone number. |
| Phone2 | The contact's backup phone number. |
| CellPhone | The contact's cell phone number. |
| EmailAddress | The contact's email address. |
PickupLocation Elements
| Element | Description |
|---|---|
| LocationType | One of the following: 100 - Address, 200 - Airport, 300 - Train station. |
| Airport | Refer to the Airport elements table. Provided if the LocationType = 200. |
| TrainStation | Refer to the Train Station elements table. Provided if the LocationType = 300. |
| Address | The street address of the location. Provided if the LocationType = 100. |
| City | The location city. |
| State | The location state. Preferably 2 characters, max 10 characters. |
| Country | The location's 2 character ISO 3166-1 alpha-2 country code. Example: US |
| PostalCode | The location postal code. |
| ExtraNotes | Additional notes about the location. Example: Ring doorbell, Holiday Inn, etc. |
DropoffLocation Elements
| Element | Description |
|---|---|
| LocationType | One of the following: 100 - Address, 200 - Airport, 300 - Train station, 400 - As directed. |
| Airport | Refer to the Airport elements table. Provided if the LocationType = 200. |
| TrainStation | Refer to the Train Station elements table. Provided if the LocationType = 300. |
| Address | The street address of the location. Provided if the LocationType = 100. |
| City | The location city. |
| State | The location state. Preferably 2 characters, max 10 characters. |
| Country | The location's 2 character ISO 3166-1 alpha-2 country code. Example: US |
| PostalCode | The location postal code. |
| ExtraNotes | Additional notes about the location. Example: Apartment Building, gravel driveway, etc. |
Vehicle Elements
| Element | Description |
|---|---|
| VehicleType | One of the following values: 100: Sedan 200: Limo 250: Stretch Limo 300: SUV 350: Stretch SUV 400: Van 450: Mini-Bus 500: Motor Coach 600: Shuttle 700: Trolley 800: Carriage 900: Any |
| Description | The vehicle description. |
| MaxPassengers | The maximum number of passengers for the car. Must be greater than zero. |
| VehicleID | Information to identify the specific vehicle. |
Vendor Elements
| Element | Description |
|---|---|
| VendorCode | The vendor code for the vendor. |
| VendorName | The vendor's name. |
| PhoneNumber | The vendor's phone number. |
FormOfPayment Elements
| Element | Description |
|---|---|
| CreditCard | If present, the passenger will pay with credit card. Refer to the Reply Credit Card elements table for the child elements. |
| Cash | If present, the passenger will pay cash. |
| Check | If present, the passenger will pay with a check. |
| DirectBilling | If present, the passenger will pay through direct billing. |
Airport Elements
| Element Name | Description |
|---|---|
| AirportCode | The IATA code for the airport. |
| Flight | The flight information. For information about the child elements of this parent element, see the Flight elements table below. |
Flight Elements
| Element Name | Description |
|---|---|
| CarrierCode | The airline code. |
| FlightNumber | The flight number. |
| ArrivalDateTime | The flight arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00 |
| DepartureDateTime | The flight departure time. Only provided for the DropoffLocation element. Format: 2015-05-19T18:00:00 |
Train Station Elements
| Element Name | Required/Optional | Data Type | Description |
|---|---|---|---|
| StationCode | The station code. | ||
| StationName | The name of the station. | ||
| City | The city the station is located in. | ||
| State | The state the station is located in. Preferably 2 characters, max 10 characters. | ||
| Train | The train information. For information about the child elements of this parent element, see the Train elements table below. |
Train Child Elements
| Element Name | Description |
|---|---|
| CarrierCode | The code of the train carrier. |
| CarrierName | The name of the train carrier. |
| TrainNumber | The train number. |
| ArrivalDateTime | The train arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00 |
| DepartureDateTime | The train departure time. Only provided for the DropoffLocation element. Format: 2015-05-19T18:00:00 |
Rate Information Elements
| Element Name | Required? | Data Type | Description |
|---|---|---|---|
| RateID | Y | The rate identifier. | |
| Rate | Y | The BasePrice + ServiceCharge + SurCharge + Tax | |
| RateTypeCode | Y | The code for the rate type. Will be one of the following options: F: Flat rate H: Hourly E: Estimated amount N: Currently not available |
|
| CategoryCode | N | Extra information that will be passed back during sell request to help identify the rate. | |
| Currency | Y | The 3-letter ISO 4217 currency code for the rate amount. | |
| NoRateText | N | Explanation of rate type. Provided if RateTypeCode = N | |
| MinHours | N | The minimum number of hours for the reservation. | |
| DiscountType | N | The type of discount applied. | |
| BasePrice | N | The reservation price without taxes, surcharges or service charges. | |
| ServiceCharge | N | The service charge for the reservation. | |
| SurCharge | N | This element contains the desc attribute, with text describing the reason for the surcharge. Example: <SurCharge desc="fuel"> |
|
| Tax | N | The reservation tax. | |
| ExtraPickupCharge | N | Any additional fees for the pickup service. | |
| ExtraDropoffCharge | N | Any additional fees for the drop off service. | |
| OptionalExtraStopCharge | N | The charge for any additional stops. | |
| OptionalExtraTimeCharge | N | The charge for each additional hour. |
Credit Card Elements
| Element Name | Required? | Data Type | Description |
|---|---|---|---|
| Type | Y | The card type. | |
| Number | Y | The card number. | |
| Expiration | Y | The card expiration date. Format: 2013-02-19 |
XML Example Request
POST /api/tws/v1.0/Limo/PostBack HTTPS/1.1
Host: app2.outtask.com/
Authorization: Basic ...
Content-Type: application/xml
Content-Length: {length of content body}
<CC_LimoPostBackRequest>
<Error>
<ErrorCode />
<ErrorSource />
<ErrorDescription />
</Error>
<ReservationID>1234</ReservationID>
<Status>CB</Status>
<ConfNum/>
<CancelPolicy />
<CancelNum/>
<PrimaryPassenger>
<FirstName>Chris</FirstName>
<LastName>Miller</LastName>
<Phone>5551234567</Phone>
<Phone2>5551234568</Phone2>
<CellPhone>5551234555</CellPhone>
<EmailAddress>cmiller@example.com</EmailAddress>
</PrimaryPassenger>
<ServiceType>110</ServiceType>
<ClassOfService />
<PickupLocation>
<LocationType>100</LocationType>
<Airport>
<AirportCode />
<Flight>
<CarrierCode />
<FlightNumber />
<ArrivalDateTime />
</Flight>
</Airport>
<TrainStation>
<StationCode />
<StationName />
<City />
<State />
<Train>
<CarrierCode />
<CarrierName />
<TrainNumber />
</Train>
</TrainStation>
<Address>209 Madison St #400</Address>
<City>Alexandria</City>
<State>VA</State>
<Country>US</Country>
<PostalCode>22314</PostalCode>
<ExtraNotes />
</PickupLocation>
<DropoffLocation>
<LocationType>200</LocationType>
<Airport>
<AirportCode>DCA</AirportCode>
<Flight>
<CarrierCode>UA</CarrierCode>
<FlightNumber>333</FlightNumber>
<DepartureDateTime>2012-02-19T11:29:00</DepartureDateTime>
</Flight>
</Airport>
<TrainStation>
<StationCode />
<StationName />
<City />
<State />
<Train>
<CarrierCode />
<CarrierName />
<TrainNumber />
<DepartureDateTime />
</Train>
</TrainStation>
<Address />
<City />
<State />
<Country />
<PostalCode />
<ExtraNotes />
</DropoffLocation>
<StartDateTime>2012-02-19T09:00:00</StartDateTime>
<EndDateTime />
<PickupInstructions>pick me up</PickupInstructions>
<DropoffInstructions>None</DropoffInstructions>
<LanguageCode>en-us</LanguageCode>
<Currency>USD</Currency>
<NumPassengers>1</NumPassengers>
<RequestedDriver />
<SpecialServiceRequest />
<PickupServiceArrangement />
<DropoffServiceArrangement />
<ExtraStopArrangement />
<RateInfo>
<RateID>5</RateID>
<Rate>42.50</Rate>
<RateTypeCode>E</RateTypeCode>
<CategoryCode />
<MinHours />
<Currency>US</Currency>
<NoRateText />
<DiscountType />
<BasePrice>35.00</BasePrice>
<ServiceCharge>5.00</ServiceCharge>
<SurCharge desc="fuel">1.00</SurCharge>
<Tax>1.50</Tax>
<ExtraPickupCharge />
<ExtraDropoffCharge />
<OptionalExtraStopCharge />
<OptionalExtraTimeCharge />
<Message />
</RateInfo>
<RateDisclaimer />
<Vehicle>
<VehicleType>100</VehicleType>
<Description>This is a Sedan.</Description>
<MaxPassengers>1</MaxPassengers>
<VehicleID>12</VehicleID>
</Vehicle>
<Vendor>
<VendorCode>LML</VendorCode>
<VendorName>LimoVendor</VendorName>
<PhoneNumber>4354654654</PhoneNumber>
</Vendor>
<ProviderFeedback />
<FormOfPayment>
<Cash />
<Check />
<DirectBilling />
<CreditCard>
<Type>VI</Type>
<Number>XXXXXXXXXXXX1111</Number>
<Expiration>2013-02-19</Expiration>
</CreditCard>
</FormOfPayment>
<AccountingInfo>
<AccountingField1>715</AccountingField1>
<AccountingField2>temp@outtask.com</AccountingField2>
<AccountingField3>11</AccountingField3>
<AccountingField4>Development</AccountingField4>
<AccountingField5/>
</AccountingInfo>
</CC_LimoPostBackRequest>
Response
SAP Concur responds to the supplier request with a result message.
Content Types
application/xml
Response Body
The response will include a CC_LimoPostBackResponse parent element, with the following child elements:
Successful post:
| Element Name | Description |
|---|---|
| Success | This element contains the message detailing the change. |
Failed post:
| Element Name | Description |
|---|---|
| Version | The API version, currently 1.0. |
| Error | This element contains the error text. |
XML Example of Successful Response
HTTPS/1.1 200 OK
Content-Type: application/xml
<CC_LimoPostBackResponse>
<Success>Updated Trip Status successfully.</Success>
</CC_LimoPostBackResponse>
XML Example of Response with Rrror
<CC_LimoPostBackResponse>
<Version>1.0</Version>
<Error>This reservation does not exist in the SAP Concur database.</Error>
</CC_LimoPostBackResponse>
HOTEL-SERVICE-2
Direct Connect - Hotel v2 - Appendix
Search

Request
<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<authentication xmlns="http://www.concur.com/webservice/auth">
<userid>testLogin123</userid>
<password>txxxxxxxxxxxx;</password>
</authentication>
</Header>
<Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<OTA_HotelSearchRQ xmlns="http://www.opentravel.org/OTA/2003/05"
EchoToken="5ADE581A-8A7C-4DA5-A67B-EED4E58A80E2"
Version="4" PrimaryLangID="en" AltLangID="en" MaxResponses="100">
<POS>
<Source ISOCurrency="USD">
<RequestorID Type="1" ID="HTL011235"></RequestorID>
</Source>
</POS>
<Criteria>
<Criterion>
<Position Latitude="47.61037" Longitude="-122.20067"></Position>
<Radius Distance="5" DistanceMax="30" UnitOfMeasureCode="1"></Radius>
<StayDateRange Start="2018-02-12" End="2018-02-13"></StayDateRange>
</Criterion>
</Criteria>
</OTA_HotelSearchRQ>
</Body>
</Envelope>
Response
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
<soap:Body>
<OTA_HotelSearchRS xmlns="http://www.opentravel.org/OTA/2003/05" xmlns:ns2="http://www.concur.com/webservice/auth" AltLangID="en" EchoToken="FC6F5CDE-2D55-49A4-AE22-056AF980ADF4" PrimaryLangID="en" Version="4">
<Success/>
<Properties>
<Property ChainCode="HI" ChainName="Holiday Inn" HotelCode="22222" HotelName="Holiday Inn Express Sunshine">
<Position Latitude="47.61038" Longitude="-122.20068"/>
<Address>
<AddressLine>99 East 27th Street</AddressLine>
<CityName>Bellevue</CityName>
<PostalCode>98009</PostalCode>
<StateProv StateCode="WA">Washington</StateProv>
<CountryName Code="US">United States of America</CountryName>
</Address>
<ContactNumbers>
<ContactNumber PhoneNumber="+14255551234" PhoneTechType="1"/>
</ContactNumbers>
<Award Rating="4"/>
<HotelAmenity Code="173"/>
<HotelAmenity Code="255"/>
<TPA_Extensions>
<HotelPreference>not_preferred</HotelPreference>
<TPA_HotelPreviewImageURI>
<URL>https://production.example.com/hotel-image.jpg</URL>
</TPA_HotelPreviewImageURI>
<TPA_PropertyReferenceInfo>
<PropertyReference ReferenceCatalogCode="1376249" ReferenceCatalogName="giata"/>
</TPA_PropertyReferenceInfo>
</TPA_Extensions>
</Property>
<Property>
... additional Property nodes here for all returned hotels
</Property>
</Properties>
</OTA_HotelSearchRS>
</soap:Body>
</soap:Envelope>
Availability
The initial Search request (see above) is followed up by an multi-property Availability request. In the example request below Concur requests the availability for 13 properties. This could because the initial search only yielded 13 properties or the configuration per vendor is set to request availability for a maximum of 13 properties.
Request
<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<authentication xmlns="http://www.concur.com/webservice/auth">
<userid>testLogin123</userid>
<password>txxxxxxxxxxxx;</password>
</authentication>
</Header>
<Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<OTA_HotelAvailRQ xmlns="http://www.opentravel.org/OTA/2003/05"
EchoToken="5ADE581A-8A7C-4DA5-A67B-EED4E58A80E2"
Version="5" PrimaryLangID="en" AltLangID="en">
<POS>
<Source ISOCurrency="USD">
<RequestorID Type="1" ID="HTL011235"></RequestorID>
</Source>
</POS>
<AvailRequestSegments>
<AvailRequestSegment>
<HotelSearchCriteria>
<Criterion>
<HotelRef ChainCode="HI" HotelCode="22222"></HotelRef>
</Criterion>
<Criterion>
<HotelRef ChainCode="AB" HotelCode="50709"></HotelRef>
</Criterion>
<Criterion>
<HotelRef ChainCode="CY" HotelCode="765336"></HotelRef>
</Criterion>
<Criterion>
<HotelRef ChainCode="HH" HotelCode="468159"></HotelRef>
</Criterion>
<Criterion>
<HotelRef ChainCode="EM" HotelCode="70346"></HotelRef>
</Criterion>
<Criterion>
<HotelRef ChainCode="AB" HotelCode="52198"></HotelRef>
</Criterion>
<Criterion>
<HotelRef ChainCode="HI" HotelCode="697768"></HotelRef>
</Criterion>
<Criterion>
<HotelRef ChainCode="HH" HotelCode="14411"></HotelRef>
</Criterion>
<Criterion>
<HotelRef ChainCode="YX" HotelCode="436533"></HotelRef>
</Criterion>
<Criterion>
<HotelRef ChainCode="PW" HotelCode="459980"></HotelRef>
</Criterion>
<Criterion>
<HotelRef ChainCode="HI" HotelCode="419430"></HotelRef>
</Criterion>
<Criterion>
<HotelRef ChainCode="WY" HotelCode="92103"></HotelRef>
</Criterion>
<Criterion>
<HotelRef ChainCode="WG" HotelCode="252272"></HotelRef>
</Criterion>
</HotelSearchCriteria>
<StayDateRange Start="2018-02-12" End="2018-02-13"></StayDateRange>
<RoomStayCandidates>
<RoomStayCandidate>
<GuestCounts>
<GuestCount AgeQualifyingCode="10" Count="1"></GuestCount>
</GuestCounts>
</RoomStayCandidate>
</RoomStayCandidates>
</AvailRequestSegment>
</AvailRequestSegments>
</OTA_HotelAvailRQ>
</Body>
</Envelope>
Response
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
<soap:Body>
<OTA_HotelAvailRS xmlns="http://www.opentravel.org/OTA/2003/05" xmlns:ns2="http://www.concur.com/webservice/auth" AltLangID="en" EchoToken="FC6F5CDE-2D55-49A4-AE22-056AF980ADF4" PrimaryLangID="en" Version="5">
<Success/>
<RoomStays>
<RoomStay>
<RoomTypes>
<RoomType RoomID="b3da298f">
<RoomDescription>
<Text>Deluxe Room with sweeping view of the city. 2 queen beds and sofa bed.</Text>
</RoomDescription>
</RoomType>
</RoomTypes>
<RatePlans>
<RatePlan AvailabilityStatus="AvailableForSale" RatePlanID="TOGG3BU">
<Guarantee GuaranteeType="GuaranteeRequired" />
<CancelPenalties>
<CancelPenalty NoCancelInd="true">
<Deadline AbsoluteDeadline="2018-02-12T18:00:00"/>
</CancelPenalty>
</CancelPenalties>
<MealsIncluded Breakfast="false" />
</RatePlan>
</RatePlans>
<RoomRates>
<RoomRate RatePlanID="TOGG3BU" RoomID="b3da298f">
<Rates>
<Rate RateTimeUnit="FullDuration">
<PaymentPolicies>
<GuaranteePayment>
<AcceptedPayments>
<AcceptedPayment>
<PaymentCard>
<CardType>VISA</CardType>
</PaymentCard>
</AcceptedPayment>
</AcceptedPayments>
</GuaranteePayment>
<GuaranteePayment>
<AcceptedPayments>
<AcceptedPayment>
<PaymentCard>
<CardType>Mastercard</CardType>
</PaymentCard>
</AcceptedPayment>
</AcceptedPayments>
</GuaranteePayment>
</PaymentPolicies>
<Total AmountAfterTax="161.10" AmountBeforeTax="152.70" CurrencyCode="USD"/>
<RateDescription>
<Text>Promotional rate</Text>
<Text>Free valet/self parking and turndown service</Text>
</RateDescription>
</Rate>
</Rates>
</RoomRate>
</RoomRates>
<GuestCounts>
<GuestCount Count="1"/>
</GuestCounts>
<TimeSpan Start="2018-02-12" End="2018-02-13" />
<BasicPropertyInfo HotelCode="22222" />
</RoomStay>
<RoomStay>
<RoomTypes>
<RoomType RoomID="f7631619">
<RoomDescription>
<Text>Standard Room with garden view. 1 king bed and sofa bed.</Text>
</RoomDescription>
</RoomType>
</RoomTypes>
<RatePlans>
<RatePlan AvailabilityStatus="AvailableForSale" RatePlanID="MB4YV34">
<Guarantee GuaranteeType="Deposit"/>
<CancelPenalties>
<CancelPenalty NoCancelInd="true">
<Deadline AbsoluteDeadline="2018-02-12T18:00:00"/>
</CancelPenalty>
</CancelPenalties>
<MealsIncluded Breakfast="false" />
</RatePlan>
</RatePlans>
<RoomRates>
<RoomRate RatePlanID="MB4YV34" RoomID="f7631619">
<Rates>
<Rate RateTimeUnit="FullDuration">
<PaymentPolicies>
<GuaranteePayment>
<AcceptedPayments>
<AcceptedPayment>
<PaymentCard>
<CardType>VISA</CardType>
</PaymentCard>
</AcceptedPayment>
</AcceptedPayments>
</GuaranteePayment>
<GuaranteePayment>
<AcceptedPayments>
<AcceptedPayment>
<PaymentCard>
<CardType>Mastercard</CardType>
</PaymentCard>
</AcceptedPayment>
</AcceptedPayments>
</GuaranteePayment>
</PaymentPolicies>
<Total AmountAfterTax="149.00" AmountBeforeTax="141.23" CurrencyCode="USD"/>
<RateDescription>
<Text>Hot Deal</Text>
<Text>Free valet/self parking</Text>
</RateDescription>
</Rate>
</Rates>
</RoomRate>
</RoomRates>
<GuestCounts>
<GuestCount Count="1"/>
</GuestCounts>
<TimeSpan End="2018-02-13" Start="2018-05-12" />
<BasicPropertyInfo HotelCode="50709" />
</RoomStay>
<RoomStay>
... additional RoomStay nodes follow here for all available rooms for all hotels (properties) per
Availability request
</RoomStay>
</RoomStays>
</OTA_HotelAvailRS>
</soap:Body>
</soap:Envelope>
Search results displayed
Search results page displaying hotels, based on Search response, and their rates, based on Availability response:

WIth Availability response also cancellation information comes which can be displayed in separate popup:

Hotel Description

Request
<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<authentication xmlns="http://www.concur.com/webservice/auth">
<userid>testLogin123</userid>
<password>txxxxxxxxxxxx;</password>
</authentication>
</Header>
<Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<OTA_HotelDescriptiveInfoRQ xmlns="http://www.opentravel.org/OTA/2003/05"
EchoToken="A78F3641-8674-43F9-B58C-AD928D1A75D9"
Version="3" PrimaryLangID="en" AltLangID="en">
<POS>
<Source ISOCurrency="USD">
<RequestorID Type="1" ID="HTL011235"></RequestorID>
</Source>
</POS>
<HotelDescriptiveInfos>
<HotelDescriptiveInfo ChainCode="CY" HotelCode="419430"></HotelDescriptiveInfo>
</HotelDescriptiveInfos>
</OTA_HotelDescriptiveInfoRQ>
</Body>
</Envelope>
Response
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
<soap:Body>
<OTA_HotelDescriptiveInfoRS xmlns="http://www.opentravel.org/OTA/2003/05"
xmlns:ns2="http://www.concur.com/webservice/auth">
<Success/>
<HotelDescriptiveContents>
<HotelDescriptiveContent ChainCode="CY" HotelCode="419430" HotelName="Courtyard Prague Airport">
<HotelInfo>
<Descriptions>
<DescriptiveText>Prague (PRG): The Europort building which housed the hotel is located in front of the
arrivial and departure halls at Prague-ruzyne Airport. The hotel will have direct access to the
airport’s infrastructure and offer connections to both the walkway and transporation routes. The
conveniently located Courtyard Prague Airport provides its guests upscale accommodation outside the
buzzing city centre. Kept in a cosy elegant design, the comfortable rooms are fitted with coffee and tea
maker and nice sitting and working area. The magnificent atrium with its modern structure and nice
garden invites to stay and relax. Directly situated at Prague’s international airport, the hotel is
about 16 kilometres from the city centre and the historic castle. In the nearby surroundings, guests can
enjoy horseback riding, biking or kayaking. Oléo Pazzo Mediterranean Bistro is a contemporary restaurant
decorated in warm and coulourful style with a show kitchen and a trendy bar. Other features are a
fitness,a business center,meeting rooms.
</DescriptiveText>
</Descriptions>
</HotelInfo>
<MultimediaDescriptions>
<MultimediaDescription>
<ImageItems>
<ImageItem>
<ImageFormat>
<URL>https://iut-foto-origin.hrsstatic.com/foto/3/8/9/8/389886/389886_fi_451616.jpg</URL>
</ImageFormat>
</ImageItem>
<ImageItem>
<ImageFormat>
<URL>https://iut-foto-origin.hrsstatic.com/foto/3/8/9/8/389886/389886_u_6302064.jpg</URL>
</ImageFormat>
</ImageItem>
<ImageItem>
<ImageFormat>
<URL>https://iut-foto-origin.hrsstatic.com/foto/3/8/9/8/389886/389886_u_451896.jpg</URL>
</ImageFormat>
</ImageItem>
</ImageItems>
</MultimediaDescription>
</MultimediaDescriptions>
<TPA_Extensions>
<Description Name="First Description">
<Text>First line of first description.</Text>
<Text>Second line of first description.</Text>
</Description>
<Description>
<Text>Second description without name.</Text>
</Description>
</TPA_Extensions>
</HotelDescriptiveContent>
</HotelDescriptiveContents>
</OTA_HotelDescriptiveInfoRS>
</soap:Body>
</soap:Envelope>
Hotel Details displayed

Reservation


Request
<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<authentication xmlns="http://www.concur.com/webservice/auth">
<userid>testLogin123</userid>
<password>txxxxxxxxxxxx;</password>
</authentication>
</Header>
<Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<OTA_HotelResRQ xmlns="http://www.opentravel.org/OTA/2003/05"
EchoToken="6C85DDBD-EB62-444D-B2C3-F59BDF65BE98"
Version="6" PrimaryLangID="en" AltLangID="en">
<POS>
<Source ISOCurrency="USD">
<RequestorID Type="1" ID="HTL011235"></RequestorID>
</Source>
</POS>
<HotelReservations>
<HotelReservation>
<RoomStays>
<RoomStay>
<RatePlans>
<RatePlan RatePlanID="XNFYP4I">
<Guarantee GuaranteeType="CC/DC/Voucher">
<GuaranteesAccepted>
<GuaranteeAccepted>
<PaymentCard CardCode="VI" ExpireDate="1220">
<CardType Code="VI">VISA</CardType>
<CardHolderName>HOTELSERVICEAMADEUS TESTUSERMOCK</CardHolderName>
</PaymentCard>
</GuaranteeAccepted>
</GuaranteesAccepted>
</Guarantee>
</RatePlan>
</RatePlans>
<TimeSpan Start="2018-02-12" End="2018-02-13"></TimeSpan>
<BasicPropertyInfo HotelCode="419430"></BasicPropertyInfo>
</RoomStay>
</RoomStays>
<ResGuests>
<ResGuest>
<Profiles>
<ProfileInfo>
<Profile>
<Customer Gender="Unknown">
<PersonName Language="en">
<GivenName>HOTELSERVICEAMADEUS</GivenName>
<Surname>TESTUSERMOCK</Surname>
</PersonName>
<Telephone PhoneNumber="3141011001"></Telephone>
<Email>hrs_hs2_amadeus_mock@concurautm3.com</Email>
<Address>
<AddressLine>123 Sesame St.</AddressLine>
<CityName>Alexandria</CityName>
<PostalCode>22314</PostalCode>
<StateProv></StateProv>
<CountryName Code="US">USA</CountryName>
</Address>
<CitizenCountryName Code="US"></CitizenCountryName>
</Customer>
<CompanyInfo>
<CompanyName>CONCURTECH</CompanyName>
</CompanyInfo>
</Profile>
</ProfileInfo>
</Profiles>
<GuestCounts>
<GuestCount Count="1"></GuestCount>
</GuestCounts>
</ResGuest>
</ResGuests>
</HotelReservation>
</HotelReservations>
</OTA_HotelResRQ>
</Body>
</Envelope>
Response
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
<soap:Body>
<OTA_HotelResRS xmlns="http://www.opentravel.org/OTA/2003/05"
xmlns:ns2="http://www.concur.com/webservice/auth"
ResResponseType="Reserved">
<Success/>
<HotelReservations>
<HotelReservation>
<UniqueID ID="88618333"/>
<RoomStays>
<RoomStay>
<RatePlans>
<RatePlan RatePlanID="EZ57LL7">
<CancelPenalties CancelPolicyIndicator="true">
<CancelPenalty>
<PenaltyDescription>
<Text>test cancel policy 1</Text>
</PenaltyDescription>
</CancelPenalty>
<CancelPenalty>
<Deadline AbsoluteDeadline="2018-02-22T18:00"/>
</CancelPenalty>
</CancelPenalties>
</RatePlan>
</RatePlans>
<RoomRates>
<RoomRate>
<Rates>
<Rate RoomPricingType="Per stay">
<PaymentPolicies>
<GuaranteePayment>
<AcceptedPayments>
<AcceptedPayment>
<PaymentCard CardCode="VI"/>
</AcceptedPayment>
</AcceptedPayments>
</GuaranteePayment>
<GuaranteePayment>
<AcceptedPayments>
<AcceptedPayment>
<PaymentCard CardCode="MC"/>
</AcceptedPayment>
</AcceptedPayments>
</GuaranteePayment>
<GuaranteePayment>
<AcceptedPayments>
<AcceptedPayment>
<PaymentCard CardCode="CA"/>
</AcceptedPayment>
</AcceptedPayments>
</GuaranteePayment>
<GuaranteePayment>
<AcceptedPayments>
<AcceptedPayment>
<PaymentCard CardCode="IK"/>
</AcceptedPayment>
</AcceptedPayments>
</GuaranteePayment>
<GuaranteePayment>
<AcceptedPayments>
<AcceptedPayment>
<PaymentCard CardCode="AX"/>
</AcceptedPayment>
</AcceptedPayments>
</GuaranteePayment>
</PaymentPolicies>
<Total AmountAfterTax="85.00" AmountBeforeTax="85.00" CurrencyCode="EUR"/>
</Rate>
</Rates>
</RoomRate>
</RoomRates>
<TimeSpan End="2018-02-23" Start="2018-02-22"/>
<BasicPropertyInfo HotelCode="50709" HotelName="Alexander Plaza">
<Address>
<AddressLine>Rosenstr. 1</AddressLine>
<CityName>Berlin</CityName>
<CountryName Code="DEU">Federal Republic of Germany</CountryName>
<StateProv StateCode="BE">Berlin disctrict</StateProv>
<PostalCode>BE123</PostalCode>
</Address>
<ContactNumbers>
<ContactNumber PhoneNumber="3024001722"/>
</ContactNumbers>
</BasicPropertyInfo>
</RoomStay>
</RoomStays>
<ResGuests>
<ResGuest>
<Profiles>
<ProfileInfo>
<Profile>
<Customer>
<PersonName>
<GivenName>TESTER</GivenName>
<Surname>Testovic</Surname>
</PersonName>
</Customer>
</Profile>
</ProfileInfo>
</Profiles>
</ResGuest>
</ResGuests>
<ResGlobalInfo>
<Comments>
<Comment Name="Comment 1">
<Text>First line of Comment 1.</Text>
<Text>Second line of Comment 1.</Text>
</Comment>
<Comment>
<Text>First line of Comment 2 without name.</Text>
</Comment>
</Comments>
</ResGlobalInfo>
</HotelReservation>
</HotelReservations>
</OTA_HotelResRS>
</soap:Body>
</soap:Envelope>
Read

Request
<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<authentication xmlns="http://www.concur.com/webservice/auth">
<userid>testLogin123</userid>
<password>txxxxxxxxxxxx;</password>
</authentication>
</Header>
<Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<OTA_ReadRQ xmlns="http://www.opentravel.org/OTA/2003/05"
EchoToken="4E1B8BF4-ACBD-4709-9FCC-B59EB2550086"
Version="5.002" PrimaryLangID="en" AltLangID="en">
<POS>
<Source ISOCurrency="USD">
<RequestorID Type="1" ID="HTL011235"></RequestorID>
</Source>
</POS>
<UniqueID Type="14" ID="88618333"></UniqueID>
</OTA_ReadRQ>
</Body>
</Envelope>
Response
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
<soap:Body>
<OTA_HotelResRS xmlns="http://www.opentravel.org/OTA/2003/05"
xmlns:ns2="http://www.concur.com/webservice/auth"
ResResponseType="Reserved">
<Success/>
<HotelReservations>
<HotelReservation>
<UniqueID ID="88621190"/>
<RoomStays>
<RoomStay>
<RatePlans>
<RatePlan RatePlanID="P4PGI5Q">
<CancelPenalties CancelPolicyIndicator="true">
<CancelPenalty>
<PenaltyDescription>
<Text>test cancel policy 1</Text>
</PenaltyDescription>
</CancelPenalty>
<CancelPenalty>
<PenaltyDescription>
<Text>test cancel policy 2</Text>
</PenaltyDescription>
<PenaltyDescription>
<Text>test cancel policy 3</Text>
</PenaltyDescription>
</CancelPenalty>
<CancelPenalty>
<Deadline AbsoluteDeadline="2018-02-22T18:00"/>
</CancelPenalty>
</CancelPenalties>
</RatePlan>
</RatePlans>
<RoomRates>
<RoomRate>
<Rates>
<Rate RoomPricingType="Per stay">
<PaymentPolicies>
<GuaranteePayment>
<AcceptedPayments>
<AcceptedPayment>
<PaymentCard CardCode="VI"/>
</AcceptedPayment>
</AcceptedPayments>
</GuaranteePayment>
<GuaranteePayment>
<AcceptedPayments>
<AcceptedPayment>
<PaymentCard CardCode="MC"/>
</AcceptedPayment>
</AcceptedPayments>
</GuaranteePayment>
<GuaranteePayment>
<AcceptedPayments>
<AcceptedPayment>
<PaymentCard CardCode="CA"/>
</AcceptedPayment>
</AcceptedPayments>
</GuaranteePayment>
<GuaranteePayment>
<AcceptedPayments>
<AcceptedPayment>
<PaymentCard CardCode="IK"/>
</AcceptedPayment>
</AcceptedPayments>
</GuaranteePayment>
<GuaranteePayment>
<AcceptedPayments>
<AcceptedPayment>
<PaymentCard CardCode="AX"/>
</AcceptedPayment>
</AcceptedPayments>
</GuaranteePayment>
</PaymentPolicies>
<Total AmountAfterTax="208.95" AmountBeforeTax="208.95" CurrencyCode="EUR"/>
</Rate>
</Rates>
</RoomRate>
</RoomRates>
<TimeSpan End="2018-02-23" Start="2018-02-22"/>
<BasicPropertyInfo ChainCode="1609" HotelCode="10517" HotelName="Radisson Blu Hotel">
<Address>
<AddressLine>Karl-Liebknecht-Str. 3</AddressLine>
<CityName>Berlin</CityName>
<CountryName Code="DEU">Federal Republic of Germany</CountryName>
<StateProv StateCode="BE">Berlin disctrict</StateProv>
<PostalCode>BE123</PostalCode>
</Address>
<ContactNumbers>
<ContactNumber PhoneNumber="30238280"/>
</ContactNumbers>
</BasicPropertyInfo>
</RoomStay>
</RoomStays>
<ResGuests>
<ResGuest>
<Profiles>
<ProfileInfo>
<Profile>
<Customer>
<PersonName>
<GivenName>TESTER</GivenName>
<Surname>Testovic</Surname>
</PersonName>
</Customer>
</Profile>
</ProfileInfo>
</Profiles>
</ResGuest>
</ResGuests>
<ResGlobalInfo>
<Comments>
<Comment Name="Comment 1">
<Text>First line of Comment 1.</Text>
<Text>Second line of Comment 1.</Text>
</Comment>
<Comment>
<Text>First line of Comment 2 without name.</Text>
</Comment>
</Comments>
</ResGlobalInfo>
</HotelReservation>
</HotelReservations>
</OTA_HotelResRS>
</soap:Body>
</soap:Envelope>
Itinerary displayed

Cancel

Request
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<authentication xmlns="http://www.concur.com/webservice/auth">
<userid>testLogin123</userid>
<password>txxxxxxxxxxxx;</password>
</authentication>
</Header>
<Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<OTA_CancelRQ xmlns="http://www.opentravel.org/OTA/2003/05" CancelType="Cancel"
EchoToken="2186EB84-23D9-4977-B8A5-B5083C8DE228"
Version="3" PrimaryLangID="en" AltLangID="en">
<POS>
<Source ISOCurrency="USD">
<RequestorID Type="1" ID="HTL011235"></RequestorID>
</Source>
</POS>
<UniqueID Type="14" ID="88618333"></UniqueID>
</OTA_CancelRQ>
</Body>
</Envelope>
Response
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
<soap:Body>
<OTA_CancelRS xmlns="http://www.opentravel.org/OTA/2003/05"
xmlns:ns2="http://www.concur.com/webservice/auth"
Status="Cancelled">
<Success/>
<UniqueID ID="88618333" Type="14"/>
<UniqueID ID="27607" Type="15"/>
</OTA_CancelRS>
</soap:Body>
</soap:Envelope>

Direct Connect - Hotel v2 - Availability
Message to retrieved the availability of hotels.
| SOAPAction | OTA Name | Message Structure |
|---|---|---|
| availability | HotelAvail | OTA_HotelAvailRQ |
- Request
- Response
- Schema
- Room Stays
- Room Stay
- Room Types
- Room Type
- Room Description
- Rate Plans
- Rate Plan
- Rate Plan Description
- Guarantee
- Supported Guarantee Types
- Supported Guarantee Required
- Deadline
- Cancel Penalties
- Cancel Penalty
- Meals Included
- Rooms Rates
- Room Rate
- Rates
- Rate
- Payment Policies
- Guarantee Payment
- Accepted Payments
- Accepted Payment
- Payment Card
- Card Type
- Total
- Rate Description
- TPA Extensions
- TimeSpan
- Basic Property Info
- Relationship Between RoomID and RatePlanID
Request
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<authentication xmlns="http://www.concur.com/webservice/auth">
<userid>user</userid>
<password>password</password>
</authentication>
</Header>
<Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<OTA_HotelAvailRQ xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="test_request_id" Version="5"
PrimaryLangID="de" AltLangID="de">
<POS>
<Source ISOCurrency="USD">
<RequestorID Type="1" ID="HTL011235"></RequestorID>
</Source>
</POS>
<AvailRequestSegments>
<AvailRequestSegment>
<HotelSearchCriteria>
<Criterion>
<HotelRef ChainCode="ZZ" HotelCode="111222"></HotelRef>
</Criterion>
</HotelSearchCriteria>
<StayDateRange Start="2018-10-26" End="2018-10-28"></StayDateRange>
<RoomStayCandidates>
<RoomStayCandidate>
<GuestCounts>
<GuestCount AgeQualifyingCode="10" Count="1"></GuestCount>
</GuestCounts>
</RoomStayCandidate>
</RoomStayCandidates>
<TPA_Extensions>
<SearchSessionToken>5EA6C45E55104704E4</SearchSessionToken>
</TPA_Extensions>
</AvailRequestSegment>
</AvailRequestSegments>
</OTA_HotelAvailRQ>
</Body>
</Envelope>
Schema
OTA_HotelAvailRQ
| Name | Type | Description |
|---|---|---|
AvailRequestSegments |
complex |
Required A collection of AvailRequestSegment. Each segment includes a collection of criteria that requests a bookable entity, which may include designated rate plans, room types, amenities or services. The request can be used for guest rooms or other inventory items for which availability is sought. Each segment will be presumed to have a unique date range for each request. SAP Concur will only ever send one AvailRequestSegments. |
AvailRequestSegments
| Name | Type | Description |
|---|---|---|
AvailRequestSegment |
complex |
Required To accommodate the ability to perform multiple requests within one message, the availability request contains the repeating element, AvailRequestSegment. Each segment includes a collection of criteria that requests a bookable entity, which may include designated rate plans, room types, amenities or services. The request can be used for guest rooms or other inventory items for which availability is sought. Each segment will be presumed to have a unique date range for each request. SAP Concur will only ever send one AvailRequestSegment. |
AvailRequestSegment
| Name | Type | Description |
|---|---|---|
HotelSearchCriteria |
complex |
Required Specified hotel search criteria. SAP Concur will send only one (1) HotelSearchCriteria. |
StayDateRange |
complex |
Range of dates using ISO 8601. |
TPA_Extensions/SearchSessionToken |
stringLength1to128 |
The token obtained from Search response that links the Search results to Availability and Reservation requests. |
HotelSearchCriteria
| Name | Type | Description |
|---|---|---|
Criterion |
complex |
Required Refer to Criterion in Search. Note that for Availability the Criterion will only have the HotelRef element. Other elements will not be sent. HotelSearchCriteria can contain multiple Criterion elements. Each will have a unique HotelCode per Availability request. |
Criterion
| Name | Type | Description |
|---|---|---|
HotelRef/HotelCode |
stringLength1to16 |
Required The code that uniquely identifies a single hotel property. The hotel code is decided by vendors. |
HotelRef/ChainCode |
stringLength1to8 |
The code that identifies a hotel chain or management group. The hotel chain code is decided between vendors. This attribute is optional if the hotel is an independent property that can be identified by the HotelCode attribute. |
StayDateRange
| Name | Type | Description |
|---|---|---|
Start |
date, or time, or datetime |
Required The starting value of the time span. |
End |
date, or time, or datetime |
Required The ending value of the time span. |
RoomStayCandidates
| Name | Type | Description |
|---|---|---|
RoomStayCandidate |
complex |
Required Element used to identify available room products. |
RoomStayCandidate
| Name | Type | Description |
|---|---|---|
GuestCounts |
complex |
Required A collection of guest counts associated with room stay. |
GuestCounts
| Name | Type | Description |
|---|---|---|
GuestCount |
complex |
Required A recurring element that identifies the number of guests and ages of the guests. It currently contains hardcoded values only. See GuestCount below. |
GuestCount
| Name | Type | Description |
|---|---|---|
Count |
integer |
Required SAP Concur only supports one guest. Supported values: 1 |
AgeQualifyingCode |
integer |
Required Supported values: 10 |
Response
The maximum allowed size of OTA_HotelAvailRS is 5 MB. Any response that exceeds this limit shall be dropped.
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
<soap:Body>
<OTA_HotelAvailRS xmlns="http://www.opentravel.org/OTA/2003/05" Version="5">
<Success/>
<RoomStays>
<RoomStay>
<RoomTypes>
<RoomType RoomID="1">
<RoomDescription>
<Text>Test room description.</Text>
</RoomDescription>
</RoomType>
</RoomTypes>
<RatePlans>
<RatePlan RatePlanID="XNFYP4I" AvailabilityStatus="ChangeDuringStay">
<Guarantee GuaranteeType="GuaranteeRequired" />
<CancelPenalties>
<CancelPenalty NoCancelInd="true">
<Deadline AbsoluteDeadline="2017-01-26T18:00:00"/>
<PenaltyDescription>
<Text>REFUNDABLE</Text>
<Text>Cancellation without penalty allowed before 2017-01-26T18:00:00</Text>
</PenaltyDescription>
</CancelPenalty>
</CancelPenalties>
<MealsIncluded Breakfast="true"/>
<RatePlanDescription>
<Text>Test rate plan description.</Text>
</RatePlanDescription>
</RatePlan>
</RatePlans>
<RoomRates>
<RoomRate RoomID="1" RatePlanID="XNFYP4I">
<Rates>
<Rate RateTimeUnit="FullDuration">
<PaymentPolicies>
<GuaranteePayment>
<AcceptedPayments>
<AcceptedPayment>
<PaymentCard CardCode="VI"/>
</AcceptedPayment>
</AcceptedPayments>
</GuaranteePayment>
</PaymentPolicies>
<Total AmountAfterTax="348.00" AmountBeforeTax="248.00" CurrencyCode="EUR"/>
<RateDescription>
<Text>Test rate description. Both before and after tax.</Text>
</RateDescription>
<TPA_Extensions>
<RequireSeriesCode>true</RequireSeriesCode>
</TPA_Extensions>
</Rate>
</Rates>
</RoomRate>
</RoomRates>
<TimeSpan End="2018-10-28" Start="2018-10-26"/>
<BasicPropertyInfo HotelCode="419430"/>
</RoomStay>
</RoomStays>
<TPA_Extensions RateDetailsInd="false"></TPA_Extensions>
</OTA_HotelAvailRS>
</soap:Body>
</soap:Envelope>
Schema
OTA_HotelAvailRS
| Name | Type | Description |
|---|---|---|
RoomStays |
complex |
Required A collection of details on the room stay including time span of this room stay, and financial information related to the room stay, including guarantee, deposit, payment, and cancellation penalties. |
TPA_Extensions/RateDetailsInd |
boolean |
If true or omitted, ratedetails will not be called to retrieve the cancellation policy and rate change details; if false, ratedetails will be called. |
RoomStays
| Name | Type | Description |
|---|---|---|
RoomStay |
complex |
Details on the room stay including time span of this room stay, and financial information related to the room stay, including guarantee, deposit, payment, and cancellation penalties. A room stay represents one (1) hotel. It can be excluded to identify there is no rate available at the hotel. |
RoomStay
For a description of the relationship between the RoomID and RatePlanID refer to "Relationship between RoomID and RatePlanID".
| Name | Type | Description |
|---|---|---|
RoomTypes |
complex |
Required Details on the room type. |
RatePlans |
complex |
Required A collection of rate plans associated with a particular room stay. The rate plan element is used to contain all the rate information for a single rate plan Code (example: RACK) for a given date range. A given rate plan may have variable rates, over the effective period of the rate plan, this is represented by the child element rates. |
RoomRates |
complex |
Required List of room rates. |
TimeSpan |
datetimespan |
Required The time span which covers the room stay. The attributes of the OTA DateTimeSpan data type are based on the W3C base data types of timeInstant and timeDuration using ISO 8601. |
BasicPropertyInfo |
complex |
Property Information for the room stay. |
RoomTypes
| Name | Type | Description |
|---|---|---|
RoomType |
complex |
Required Provides details regarding rooms, usually guest rooms. The room description text will be used for each room (defined as a RoomRate) which specifies the same RoomID. |
RoomType
| Name | Type | Description |
|---|---|---|
RoomID |
stringLength1to16 |
Required A string value representing the unique identification of a room if the request is looking for a specific room type. |
RoomDescription |
complex |
Textual information regarding the room. |
RoomDescription
| Name | Type | Description |
|---|---|---|
Text |
string |
Required If multiple text elements are provided, the contents will be concatenated. All text passed is HTML encoded. |
RatePlans
| Name | Type | Description |
|---|---|---|
RatePlan |
complex |
Required Defines the details of the rate plan as used in the booking process. Policies and descriptions that apply to a rate plan. Information significant to defining a rate plan. |
RatePlan
| Name | Type | Description |
|---|---|---|
RatePlanID |
stringLength1to64 |
Required A text field used to indicate a special ID code that is associated with the rate and is essential in the reservation request in order to obtain the rate. Examples: Corporate ID. |
AvailabilityStatus |
stringLength1to32 |
Required Used to specify an availability status for the rate plan. Supported values: AvailableForSale, ChangeDuringStay. |
Guarantee |
complex |
Required Guarantee information that applies to the rate plan. SAP Concur only expects one (1) Guarantee element per RatePlan. |
CancelPenalties |
complex |
Required if RateDetailsInd is true or not present Collection of cancellation penalties. If the cancel penalties are not provided SAP Concur will display: "Cancellation policy not provided by vendor". |
MealsIncluded |
complex |
Defines which meals are included with this rate program. |
RatePlanDescription |
complex |
Textual information regarding the Rate Plan. |
RatePlanDescription
| Name | Type | Description |
|---|---|---|
Text |
string |
Required If multiple text elements are specified, the contents of this element will be rendered as a paragraph. All text passed is HTML encoded. |
Guarantee
| Name | Type | Description |
|---|---|---|
GuaranteeType |
string |
Required The guarantee information to hold a reservation. |
Supported GuaranteeTypes
| GuaranteeType | Description |
|---|---|
Deposit |
In SAP Concur this value is seen as RequiredDeposit. |
DepositRequired |
In SAP Concur this value is seen as RequiredDeposit. |
CC/DC/Voucher |
In SAP Concur this value is seen as RequiredGuarantee. |
PrePay |
In SAP Concur this value is seen as RequiredPrepay. |
None |
In SAP Concur this value is seen as Never. No guarantee is required if user books a room with this type. |
GuaranteeRequired |
RequiredGuarantee. If the Guarantee type cannot be mapped to any accepted type, it will be set to RequiredGuarantee. This value is the default. |
Supported GuaranteeRequired
| GuaranteeRequired | Description |
|---|---|
always |
Guarantee is required all the time independently on deposit account setting. |
never |
Guarantee is never required. |
default |
Guarantee is required if no deposit account is set up. |
CancelPenalties
| Name | Type | Description |
|---|---|---|
CancelPenalty |
complex |
Required Defines the cancellation penalty of the hotel facility. |
CancelPenalty
| Name | Type | Description |
|---|---|---|
NoCancelInd |
boolean |
If true, the reservation cannot be cancelled once the cancellation deadline has expired. False or missing flag will be treated as rate being not cancellable. |
PenaltyDescription |
complex |
Text description of the penalty in a given language. This element may contain a maximum of 9 children text fields. Any excess text elements are dropped. |
Deadline |
complex |
Cancellation deadline. |
PenaltyDescription
| Name | Type | Description |
|---|---|---|
Text |
string |
Required Formatted text content in a given language. All text passed is HTML encoded. |
Deadline
| Name | Type | Description |
|---|---|---|
AbsoluteDeadline |
time or datetime |
Required Defines the absolute deadline in ISO8601 format and in UTC timezone. |
MealsIncluded
| Name | Type | Description |
|---|---|---|
Breakfast |
boolean |
If true, indicates breakfast is included. If false, indicates it is excluded. In both cases this information is shown to a customer in the rate description. The MealsIncluded element must be omitted to avoid any adjustment to the rate description. |
RoomRates
| Name | Type | Description |
|---|---|---|
RoomRate |
complex |
Required Contains the rate details. |
RoomRate
| Name | Type | Description |
|---|---|---|
RoomID |
stringLength1to16 |
Required Room Type ID. The combination of RoomID and RatePlanID must be unique for a RoomStay. |
RatePlanID |
stringLength1to64 |
Required Rate plan ID for which this rate is applicable for. |
Rates |
complex |
Required Contains the rate for the given room. SAP Concur only expects one (1) rate inside the Rates element. Refer to Rate Details for rate change details. |
Rates
| Name | Type | Description |
|---|---|---|
Rate |
complex |
Required Contains the rate for the given room. Only one (1) Rate element is expected. Refer to Rate Details for rate change details. |
Rate
| Name | Type | Description |
|---|---|---|
RateTimeUnit |
string |
Indicates the time unit for the rate. Supported values: FullDuration, Day. Default: FullDuration |
PaymentPolicies |
complex |
Payment policies for this rate. |
Total |
complex |
Required A description of the rate. |
RateDescription |
complex |
A textual description of a rate. Only one (1) Rate Description element is expected. |
TPA_extensions |
complex |
TPA extensions for a rate. |
PaymentPolicies
| Name | Type | Description |
|---|---|---|
GuaranteePayment |
complex |
Element containing the guarantee payment type. |
GuaranteePayment
| Name | Type | Description |
|---|---|---|
AcceptedPayments |
complex |
Required If used, at least one (1) AcceptedPayment should be present. |
AcceptedPayments
| Name | Type | Description |
|---|---|---|
AcceptedPayment |
complex |
Required Accepted payment type. |
AcceptedPayment
| Name | Type | Description |
|---|---|---|
PaymentCard |
complex |
Required Description of payment type. |
PaymentCard
| Name | Type | Description |
|---|---|---|
CardType |
complex |
Required String representation of a card type. Allowed values: AmericanExpress, BankOfAmerica, BritishAirways, CapitalOne, Chase, Citibank, ContinentalAirlines, DeltaAirlines, DiscoverCard, Disney, Eurocard, Hilton, Hyatt, Mariott, Mastercard, RitzCarlton, SouthwestAirlines, StarwoodHotels, UnitedAirlines, USAirways, VISA, Other_. See Code and Description if card type is other_. |
CardType
| Name | Type | Description |
|---|---|---|
Code |
string |
If CardType is Other_, use this attribute for card code. Examples: AX, VI. |
Description |
string |
If CardType is Other_, use this attribute for card description. |
Total
| Name | Type | Description |
|---|---|---|
AmountBeforeTax |
string |
The total amount not including any associated tax. Examples: sales tax, VAT, GST |
AmountAfterTax |
string |
Required The total amount including all associated taxes. Examples: sales tax, VAT, GST |
CurrencyCode |
alphaLength3 |
Required Currency code. |
RateDescription
| Name | Type | Description |
|---|---|---|
Text |
string |
Required If multiple text elements are provided, the contents will be concatenated. All text passed is HTML encoded. |
TPA_Extensions
| Name | Type | Description |
|---|---|---|
RequireSeriesCode |
boolean |
If true, the CVV code is required for the given rate. When false or not provided, the rate will be treated as CVV code not required. |
Timespan
| Name | Type | Description |
|---|---|---|
Start |
date, time, or datetime |
Required The starting value of the time span. |
End |
date, time, or datetime |
Required The ending value of the time span. |
BasicPropertyInfo
| Name | Type | Description |
|---|---|---|
HotelCode |
complex |
Required Refer to the Property element described in Search. |
Relationship between RoomID and RatePlanID
The combination of these IDs must be unique per RoomStay. IDs with the same values can be redefined in multiple RoomStays.
<OTA_HotelAvailRS>
<Success/>
<!-- Hotel #1 with 3 rates -->
<RoomStays>
<RoomStay>
<RoomTypes>
<RoomType RoomID="RT1">...</RoomType>
<RoomType RoomID="RT2">...</RoomType>
</RoomTypes>
<RatePlans> <!-- Contains cancellation policy info, guarantee type etc. -->
<RatePlan AvailabilityStatus="AvailableForSale" RatePlanID="RP1">...</RatePlan>
<RatePlan AvailabilityStatus="AvailableForSale" RatePlanID="RP2">...</RatePlan>
<RatePlan AvailabilityStatus="AvailableForSale" RatePlanID="RP3">...</RatePlan>
</RatePlans>
<RoomRates> <!-- Represents unique rate (hotel room), contains description part 1, rate cost & supported credit card etc. -->
<RoomRate RatePlanID="RP1" RoomID="RT1">...</RoomRate>
<RoomRate RatePlanID="RP2" RoomID="RT2">...</RoomRate> <!-- Note: RT2 is reused in two Room Rates -->
<RoomRate RatePlanID="RP3" RoomID="RT2">...</RoomRate>
</RoomRates>
...
</RoomStay>
</RoomStays>
<!-- Hotel #2 with 2 rates -->
<RoomStays>
<RoomStay>
<RoomTypes>
<RoomType RoomID="RT1">...</RoomType>
<RoomType RoomID="RT2">...</RoomType>
</RoomTypes>
<RatePlans>
<RatePlan AvailabilityStatus="AvailableForSale" RatePlanID="RP1">...</RatePlan>
<RatePlan AvailabilityStatus="AvailableForSale" RatePlanID="RP2">...</RatePlan>
</RatePlans>
<RoomRates>
<RoomRate RatePlanID="RP1" RoomID="RT1">...</RoomRate>
<RoomRate RatePlanID="RP2" RoomID="RT2">...</RoomRate>
</RoomRates>
...
</RoomStay>
</RoomStays>
...
</OTA_HotelAvailRS>
Direct Connect - Hotel v2 - Cancel
Cancel
Message used to indicate to the hotel supplier that a given reservation should be cancelled.
| SOAPAction | OTA Name | Message Structure |
|---|---|---|
| cancel | Cancel | OTA_CancelRQ |
Request
<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<authentication xmlns="http://www.concur.com/webservice/auth">
<userid>user</userid>
<password>password</password>
</authentication>
</Header>
<Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<OTA_CancelRQ xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="test_request_id" Version="3"
PrimaryLangID="en" AltLangID="en" CancelType="Cancel">
<POS>
<Source ISOCurrency="USD">
<RequestorID Type="1" ID="HTL011235"></RequestorID>
</Source>
</POS>
<UniqueID Type="14" ID="11112222"></UniqueID>
</OTA_CancelRQ>
</Body>
</Envelope>
OTA_CancelRQ
| Name | Type | Description |
|---|---|---|
UniqueID |
complex |
Required Element to hold the type and the ID of the reservation to be cancelled. |
UniqueID
| Name | Type | Description |
|---|---|---|
Type |
string |
Required UniqueID with Type of 14 identifies the reservation to cancel. |
ID |
stringLength1to32 |
Required A unique identifying value assigned by the creating system. |
Response
The maximum allowed size of OTA_CancelRS is 150 KB. Any response that exceeds this limit shall be dropped.
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
<soap:Body>
<OTA_CancelRS xmlns="http://www.opentravel.org/OTA/2003/05" Version="3" Status="Cancelled">
<Success/>
<UniqueID ID="11112222" Type="14"/>
<UniqueID ID="12122" Type="15"/>
</OTA_CancelRS>
</soap:Body>
</soap:Envelope>
OTA_CancelRS
| Name | Type | Description |
|---|---|---|
Status |
string |
Required Supported values: Cancelled, Unsuccessful |
Success |
successType |
An element that is not intended to contain any data. The mere presence of a success element within the response message indicates that the incoming request message was processed successfully. |
UniqueID |
string |
Required See UniqueID above. SAP Concur expects two (2) UniqueIDs to be returned in the response. The first with an Type of 14 containing the original reservation number, and the second Type of 15 containing a confirmation number. Both elements are mandatory. |
Direct Connect - Hotel v2 - Descriptive Information
Descriptive Info
Message to retrieve descriptive details about a given hotel. This may include text and/or a number of URL pointed to hosted images. Concur does not host any hotel images.
| SOAPAction | OTA Name | Message Structure |
|---|---|---|
| detail | HotelDescriptiveInfo | OTA_HotelDescriptiveInfoRQ |
Request
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<authentication xmlns="http://www.concur.com/webservice/auth">
<userid>user</userid>
<password>password</password>
</authentication>
</Header>
<Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<OTA_HotelDescriptiveInfoRQ xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="test_request_id" Version="3" PrimaryLangID="de" AltLangID="de">
<POS>
<Source ISOCurrency="USD">
<RequestorID Type="1" ID="HTL011235"></RequestorID>
</Source>
</POS>
<HotelDescriptiveInfos>
<HotelDescriptiveInfo ChainCode="AB" HotelCode="2575"></HotelDescriptiveInfo>
</HotelDescriptiveInfos>
</OTA_HotelDescriptiveInfoRQ>
</Body>
</Envelope>
OTA_HotelDescriptiveInfoRQ
| Name | Type | Description |
|---|---|---|
HotelDescriptiveInfos |
complex |
Required Collection of items for data from multiple hotels. SAP Concur will only ever send one (1) HotelDescriptiveInfo. |
HotelDescriptiveInfos
| Name | Type | Description |
|---|---|---|
HotelDescriptiveInfo |
complex |
Required This allows the requestor to indicate which specific information is requested if complete hotel details are not required. |
HotelDescriptiveInfo
| Name | Type | Description |
|---|---|---|
ChainCode |
stringLength1to8 |
The code that identifies a hotel chain or management group. The hotel chain code is decided between vendors. This attribute is optional if the hotel is an independent property that can be identified by the HotelCode attribute. |
HotelCode |
stringLength1to16 |
Required The code that uniquely identifies a single hotel property. The hotel code is decided between vendors. |
Response
The maximum allowed size of OTA_HotelDescriptiveInfoRS is 150 KB. Any response that exceeds this limit will be dropped.
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
<soap:Body>
<OTA_HotelDescriptiveInfoRS xmlns="http://www.opentravel.org/OTA/2003/05" Version="3">
<Success/>
<HotelDescriptiveContents>
<HotelDescriptiveContent ChainCode="ZZ" HotelCode="2575" HotelName="Torbräu">
<HotelInfo>
<Descriptions>
<DescriptiveText>Hotel description</DescriptiveText>
</Descriptions>
</HotelInfo>
<MultimediaDescriptions>
<MultimediaDescription>
<ImageItems>
<ImageItem>
<ImageFormat>
<URL>https://production.example.com/hotel-image.jpg</URL>
</ImageFormat>
</ImageItem>
</ImageItems>
</MultimediaDescription>
</MultimediaDescriptions>
<TPA_Extensions>
<Description Name="This will be a header">
<Text>First line of first description.</Text>
<Text>Second line of first description.</Text>
</Description>
<Description>
<Text>Second description without name.</Text>
</Description>
</TPA_Extensions>
</HotelDescriptiveContent>
</HotelDescriptiveContents>
</OTA_HotelDescriptiveInfoRS>
</soap:Body>
</soap:Envelope>
OTA_HotelDescriptiveInfoRS
| Name | Type | Description |
|---|---|---|
HotelDescriptiveContents |
complex |
Required Contains hotel details content which is made up of text and image URLs. |
HotelDescriptiveContents
| Name | Type | Description |
|---|---|---|
HotelDescriptiveContent |
complex |
Required Contains hotel details content which is made up of text and image URLs. SAP Concur expects one (1) HotelDescriptiveContent. |
HotelDescriptiveContent
| Name | Type | Description |
|---|---|---|
HotelCode |
stringLength1to16 |
Required The code that uniquely identifies a single hotel property. The hotel code is decided between vendors. |
HotelName |
stringLength1to128 |
Required A text field used to communicate the proper name of the hotel. SAP Concur always expects the Hotel Name to be provided. |
HotelInfo |
complex |
Contains descriptive information about a hotel. |
TPA_Extensions |
complex |
SAP Concur specific extensions. |
MultimediaDescriptions |
complex |
Multimedia information about a collection of multimedia objects. SAP Concur expects one (1) MultimediaDescription element. |
HotelInfo
| Name | Type | Description |
|---|---|---|
Descriptions |
complex |
Contains descriptive information about a hotel. SAP Concur expects one (1) Descriptions. |
Descriptions
| Name | Type | Description |
|---|---|---|
DescriptiveText |
string |
Descriptive text that describes the hotel. SAP Concur expects one (1) DescriptiveText |
TPA_Extensions
| Name | Type | Description |
|---|---|---|
Description |
complex |
Represents text which will be rendered in the UI in the form of a heading and a paragraph. |
Description
| Name | Type | Description |
|---|---|---|
name |
stringLength1to64 |
The contents of this element will be rendered as a heading on the hotel details page. |
Text |
string |
Required The contents of this element will be rendered as a paragraph. SAP Concur expects a maximum of 20 text elements per description, which will be concatenated to into one (1) paragraph. |
MultimediaDescriptions
| Name | Type | Description |
|---|---|---|
MultimediaDescription |
complex |
Holds a list of ImageItems, each representing a single hotel image. |
MultimediaDescription
| Name | Type | Description |
|---|---|---|
ImageItems |
complex |
Holds a list of ImageItem, each representing a single hotel image. SAP Concur expects up to a maximum of 200 ImageItem elements. |
ImageItems
| Name | Type | Description |
|---|---|---|
ImageItem |
complex |
One (1) ImageItem per hotel image. |
ImageItem
| Name | Type | Description |
|---|---|---|
ImageFormat |
complex |
Format of image. |
ImageFormat
| Name | Type | Description |
|---|---|---|
URL |
string |
Required Contains a HTTPS URL pointing to a hotel image. The URLs are used in a client-side gallery widget, which works best with .png and .jpg files. |
Direct Connect - Hotel v2 - Error Handling
SAP Concur is able to handle HTTP errors, but the preference is for the supplier to return an OTA error whenever possible. SAP Concur only ever expects one OTA error per message. Any extra errors will be ignored. Currently OTA Warnings are not supported and will be ignored.
If the error is specifically related to application level errors, please do not respond with any other error types (HTTP etc.). If you have server level issues, then it is OK to respond with HTTP standard error codes.
Errors should always be returned in a response. For example:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
<soap:Body>
<OTA_HotelSearchRS xmlns="http://www.opentravel.org/OTA/2003/05"
AltLangID="en"
EchoToken="11111111-2222-3333-4444-555555555555" PrimaryLangID="en"
Version="4">
<Errors>
<Error Code="322" ShortText="No availability" Type="13"></Error>
</Errors>
</OTA_HotelSearchRS>
</soap:Body>
</soap:Envelope>
If an error is present in any message, then the content of that message is discarded and only the error element is processed. Any text from the supplier will be logged and a SAP Concur message will be displayed to the user.
Currently SAP Concur does not support displaying of supplier generated errors directly in the UI.
SAP Concur only uses the very first error that is returned, therefore any excess error elements are dropped. Any errors without a Type attribute will automatically be treated as 1 meaning Unknown. See the Error Types table below.
| Name | Type | Description |
|---|---|---|
Errors |
complex |
Element used to hold error elements. SAP Concur only expects one (1) error element. An empty errors element will be treated as an Unknown error. |
Errors
| Name | Type | Description |
|---|---|---|
Error |
complex |
Element to describe a particular error. Extra text can be placed inside this element, however SAP Concur expects the error message to be sent in the ShortText attribute. |
Error
| Name | Type | Description |
|---|---|---|
Type |
string |
An error type code. See the Error Types below. |
ShortText |
string |
Required A description of the error. The content of this attribute will be logged, but never displayed to the user. |
Code |
string |
Required An error code for a specific error. |
Error Types
SAP Concur supports the following Error Type Codes in any of the responses:
| Code | Name | Description |
|---|---|---|
| 1 | Unknown |
Indicates an unknown error. |
| 2 | No implementation |
Indicates that the target business system has no implementation for the intended request. |
| 13 | Application error |
Indicates that an involved back-end application returned an error which is passed back in the response message. |
Note: The OTA Error-Type code of 4 - Authentication (indicates the message lacks adequate security credentials) is not expected by SAP Concur. For all authentication errors SAP Concur expects an HTTP 403.
SAP Concur expects the following errors under the given error types:
Error Type Code 1: Unknown
| Error Code | Description | Example |
|---|---|---|
| 188 | Transaction error | For errors not specified in other codes. Internal supplier log ID can be provided in ShortText for debugging. |
Error Type Code 2: No Implementation
| Error Code | Description | Example |
|---|---|---|
| 1 | Not implemented | The supplier can respond with this error if the end point called is not yet implemented. |
Error Type Code 13: Application Error
| Error Code | Description | Example |
|---|---|---|
| 242 | Credit card number is invalid or missing | Missing credit card number. |
| 320 | Invalid value | Comma separated node or attribute and sent value should be provided in the content of the error element. Example: <Error Code="320" ShortText="Invalid value" Type="13">StayDateRange:2019-11-33</Error> |
| 322 | No availability | Hotel Codes should be provided in content of the element. Example: <Error Code="322" ShortText="No availability" Type="13">HTL4444,HTL5555</Error> |
| 424 | No hotels found which match this input | Search parameters - geo-code and radius should be provided in content of the element and formatted as tokenized list: Latitude, Longitude, Radius, Unit of Measure code. Example: <Error Code="322" ShortText="No availability" Type="13">50.111,40.222,5,2</Error> |
| 95 | Booking already cancelled | Booking already cancelled. |
| 438 | Requested rate not available | List of comma separated RatePlanID's should be provided in content of the element. Example: <Error Code="322" ShortText="No availability" Type="13">111,222</Error> |
| 748 | Invalid corporate ID | Requestor ID should be provided in the content of the element. |
| 400 | Invalid property code | List of comma separated hotel codes should be provided in content of the element. Example: <Error Code="322" ShortText="No availability" Type="13">HTL4444,HTL5555</Error> |
| 385 | Invalid confirmation or cancellation number | Reservation ID should be provided in content of the element. |
Direct Connect - Hotel v2 - Headers
SAP Concur will send the user-name and password in both the HTTP header and the SOAP header. If the username and password generates an authentication error, then SAP Concur expects an HTTP 403 response.
HTTP Headers
SAP Concur will send the following HTTP headers in every request. The contents of the Authentication header will be repeated in the SOAP payload. Please note that some libraries used to handle the requests may be case sensitive.
| Name | Type | Description |
|---|---|---|
Authorization |
string |
A Base64 encoded string in the form of Basic <username:password>. |
SOAPAction |
string |
The message type. The action will always be sent in lowercase. Example: search |
Content-Type |
string |
All communication with the HS2 API is by way of a application/xml content type. |
Accept |
string |
SAP Concur will always set the Accept header to application/xml. |
Accept-Charset |
string |
SAP Concur will always set the Accept-Charset header to utf-8. |
concur-correlationid |
string |
This unique code can be used during troubleshooting as it identifies the API call in the log files. |
concur-traveleruuid |
string |
UUID that identifies the traveler within concur, will always be sent once profile creation is completed. |
concur-loginid |
string |
Login ID of traveler within concur. Only sent when available. |
Supported Soapactions:
| Soapaction | Functionality |
|---|---|
search |
Used to perform Search |
availability |
Used to perform Availability |
ratedetails |
Used to perform Rate Details |
detail |
Used to perform Hotel Description |
book |
Used to perform Reservation |
read |
Used to perform Read Itinerary |
cancel |
Used to perform Cancel |
Troubleshooting
In order to assist with troubleshooting, SAP Concur provides a unique correlationId in the request header. The key to look for is correlationid. This unique code can be used during troubleshooting as it identifies the API call in the log files. You should record this information in your own API call logs as well so that you can pass this information on to the SAP Concur support team.
Example HTTP Header from network capture:
Accept: application/xml
Accept-Charset: utf-8
Authorization: *******************
concur-correlationid: A75CE5BC-90BA-4BF8-8DEA-69FA2E66E936
concur-loginid: abc@concur.com
concur-traveleruuid: <valid uuid>
Content-Type: application/xml; charset="utf-8"
SOAPAction: search
Accept-Encoding: gzip
Soap Header
The Soap header nested in the Envelope will contain an authentication element.
authentication
| Name | Type | Description |
|---|---|---|
userid |
string |
Required Contains the authentication details. |
password |
string |
Required Contains the authentication details. |
Sample:
<Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<authentication xmlns="http://www.concur.com/webservice/auth">
<userid>testLogin123</userid>
<password>xxxxxxxxxxxx</password>
</authentication>
</Header>
Login and password are provided by the Hotel supplier for SAP Concur as API consumer, not per customer.
OTA Message Headers
Every message must contain the following required attributes and elements. On top of these each message may specify extra attributes and elements. Refer to a specific messages' page for details.
Request Message Headers
| Name | Type | Description |
|---|---|---|
EchoToken |
stringLength1to128 |
Required A reference for additional message identification, assigned by the requesting host system. |
Version |
double |
Required The OpenTravel message version indicated by a decimal value. |
PrimaryLangID |
string |
Required The primary language preference for the message encoded as ISO 639-1. |
AltLangID |
string |
Required The alternate language for a customer or message encoded as ISO 639-1. |
POS |
complex |
Required Point of Sale (POS) identifies the party or connection channel making the request. |
POS
| Name | Type | Description |
|---|---|---|
Sources |
complex |
Required This holds the details about the requestor. Max Occurrence: 10 |
Source
SAP Concur will always send the ISO Currency.
| Name | Type | Description |
|---|---|---|
ISOCurrency |
alphaLength3 |
Required Currency code. |
RequestorID |
complex |
An identifier of the entity making the request Examples: ATA/IATA/ID number, Electronic Reservation Service Provider (ERSP), Association of British Travel Agents (ABTA) |
RequestorID
| Name | Type | Description |
|---|---|---|
Type |
stringLength1to32 |
Required Supported value: 1 |
ID |
stringLength1to32 |
Required The requestor ID. |
Response Message Headers
The supplier is required to respond with the following attributes and elements in the root of any message. Each message may specify extra attributes and elements. Refer to a specific messages' page for details.
| Name | Type | Description |
|---|---|---|
EchoToken |
stringLength1to128 |
Required A reference for additional message identification, assigned by the requesting host system. When a request message includes an echo token the corresponding response message MUST include an echo token with an identical value. |
Timestamp |
datetime |
Required Timestamp of the response operation. |
Version |
double |
Required The OpenTravel message version indicated by a decimal value. |
PrimaryLangID |
string |
Required The primary language preference for the message encoded as ISO 639-1. |
AltLangID |
string |
Required The alternate language for a customer or message encoded as ISO 639-1. |
Success / Error |
complex |
Required Indicates Success Or Error. Refer to the Error Handling page for more details. |
Direct Connect - Hotel v2 - Introduction
Overview
The Hotel Services v2 Direct Connect provides a method for Travel users to access hotel inventory.
The Hotel Service 2.0 API from SAP Concur is a specification based on OTA 2015 standard for Hotel Suppliers. Please refer to XSD schema of the service and WSDL service description. This Guide provides information how the Hotel Supplier can make their content available for Concur Travel users using Hotel Service 2.0 API. Once the Hotel Supplier has developed and certified their interface with SAP Concur, their inventory will begin appearing in hotel searches by opted-in Travel users. This API has client/server architecture, where SAP Concur acts as client, pulling information from the Hotel Supplier, who acts as server, responding to SAP Concur’s requests. This guide specifies the request and response format required by SAP Concur.
This call-out differs from the in-bound SAP Concur web services in the following ways:
- It uses an out-bound message where SAP Concur calls a public facing API end-point provided by the hotel supplier.
- The supplier configures and maintains the public web service interface. This guide specifies the request and response format required by SAP Concur.
Contents
- Overview
- Product Restrictions
- Supported Operations
- Non-Functional Requirements
- URLs
- Handling of HTML
- Message Structure
Product Restrictions
SAP Concur products are highly configurable, and not all clients will have access to all features.
Supported Operations
- Search
- Availability
- Rate Details
- Hotel Description
- Reservation
- Read-Itinerary
- Cancel
Non-Functional Requirements
Payload Limits
| Operation | Maximum response content-length |
|---|---|
| Search | 1 MB |
| Availability | 5 MB |
| Descriptive Information | 150 KB |
| Rate Details | 5 MB |
| Reservation | 150 KB |
| Read Itinerary | 150 KB |
| Cancel | 150 KB |
Responses that exceed these limits will be dropped and handled as error responses.
Recommended Response Times, Timeouts, and Retries
| Operation | Ideal response time |
|---|---|
| Search | <4 seconds |
| Availability | <10 seconds |
| Descriptive Information | <1 second |
| Rate Details | <2 seconds |
| Reservation | <10 seconds |
| Read Itinerary | <1 second |
| Cancel | <10 seconds |
Achieving lower response times helps get information to the traveler sooner which leads to a better user experience. SAP Concur understands that not every hotel program manages their own inventory and requires relays out to other vendors and the numbers above take that scenario into consideration.
All endpoints carry a timeout of 55 seconds. No endpoints will attempt a retry in the event there is a timeout.
SAP Concur has monitoring in place for each endpoint and will open a ticket with suppliers if a significant degradation or variance of service quality is detected.
NOTE: To prevent no show fees, duplicate bookings and other similar issues, SAP Concur recommends the Hotel Supplier auto-cancel the reservation if a corresponding ReadRQ message is not sent by SAP Concur within 5 minutes after the HotelResRS message was sent to SAP Concur.
Maximum Connections and Throttling
SAP Concur is unable to share details regarding maximum connections and/or throttling questions due to their sensitivity in nature.
Emergency Technical Contact
The Hotel supplier needs to provide emergency technical contact email that will be used for communication in case of blocking technical issues.
Testing Environment
To allow SAP Concur performing testing, the Hotel Supplier needs to provide testing URL or specify properties for testing in production URL. SAP Concur needs to be able to perform test bookings with testing credit cards.
Security
PCI DSS Compliance
As sensitive data and payment card details are transferred via API, the Hotel Suppliers need to comply with PCI DSS standard. SAP Concur is compliant with PCI DSS standard and undergoes regular security audits.
HTTPS
SAP Concur requires TLS 1.2 (Transport Layer Security) SSL protocol for file transfers. The Hotel Supplier will provide SAP Concur HTTPS URL of its end-point. Standard HTTPS port 443 should be used.
URLs
SAP Concur will receive a single URL from the Hotel Supplier. All requests will go to that URL.
For details of all required HTTP headers refer to Headers
SAP Concur is using date as xs:date XML type "2017-05-01".
Handling of HTML
CDATA and HTML code inside of XML nodes and attributes are not allowed. These data will be escaped. The hotel suppliers should not use XML special characters - predefined entities: &, <, >, ", ' inside of ID elements like RatePlanID.
Message Structure
All messages to and from the HS2 API follow this structure:
Requests
- Envelope
- Header
- Body
- OTA_
RQ
Note: The Header element in a request must contain the Authentication element.
Responses
- Envelope
- Header
- Body
- OTA_
RS
Note: The header in the response does not need the Authentication element.
Direct Connect - Hotel v2 - Rate Details
Message to retrieve the details of a hotel rate.
| SOAPAction | OTA Name | Message Structure |
|---|---|---|
| ratedetails | HotelAvail | OTA_HotelAvailRQ |
- Request
- Response
- Schema
- Room Stays
- Room Stay
- Room Types
- Room Type
- Room Description
- Rate Plans
- Rate Plan
- Rate Plan Description
- Guarantee
- Supported Guarantee Types
- Supported Guarantee Required
- Deadline
- Cancel Penalties
- Cancel Penalty
- Meals Included
- Rooms Rates
- Room Rate
- Rates
- Rate
- RoomRateDescription
- Payment Policies
- Guarantee Payment
- Accepted Payments
- Accepted Payment
- Payment Card
- Card Type
- Total
- Rate Description
- Timespan
- Basic Property Info
Request
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<authentication xmlns="http://www.concur.com/webservice/auth">
<userid>user</userid>
<password>password</password>
</authentication>
</Header>
<Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<OTA_HotelAvailRQ xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="test_request_id" Version="5"
PrimaryLangID="de" AltLangID="de" RateDetailsInd="true">
<POS>
<Source ISOCurrency="USD">
<RequestorID Type="1" ID="HTL011235"></RequestorID>
</Source>
</POS>
<AvailRequestSegments>
<AvailRequestSegment>
<HotelSearchCriteria>
<Criterion>
<RatePlanCandidates>
<RatePlanCandidate RatePlanID="XNFYP4I">
<HotelRefs>
<HotelRef ChainCode="ZZ" HotelCode="111222"></HotelRef>
</HotelRefs>
</RatePlanCandidate>
</RatePlanCandidates>
</Criterion>
</HotelSearchCriteria>
<StayDateRange Start="2018-10-26" End="2018-10-28"></StayDateRange>
<RoomStayCandidates>
<RoomStayCandidate>
<GuestCounts>
<GuestCount AgeQualifyingCode="10" Count="1"></GuestCount>
</GuestCounts>
</RoomStayCandidate>
</RoomStayCandidates>
<TPA_Extensions>
<SearchSessionToken>5EA6C45E55104704E4</SearchSessionToken>
</TPA_Extensions>
</AvailRequestSegment>
</AvailRequestSegments>
</OTA_HotelAvailRQ>
</Body>
</Envelope>
Schema
OTA_HotelAvailRQ
| Name | Type | Description |
|---|---|---|
RateDetailsInd |
boolean |
Required Always set to true for ratedetails. |
AvailRequestSegments |
complex |
Required A collection of AvailRequestSegment. Each segment includes a collection of criteria that requests a bookable entity, which may include designated rate plans, room types, amenities or services. The request can be used for guest rooms or other inventory items for which availability is sought. Each segment will be presumed to have a unique date range for each request. SAP Concur will only ever send one AvailRequestSegments. |
AvailRequestSegments
| Name | Type | Description |
|---|---|---|
AvailRequestSegment |
complex |
Required To accommodate the ability to perform multiple requests within one message, the availability request contains the repeating element, AvailRequestSegment. Each segment includes a collection of criteria that requests a bookable entity, which may include designated rate plans, room types, amenities or services. The request can be used for guest rooms or other inventory items for which availability is sought. Each segment will be presumed to have a unique date range for each request. SAP Concur will only ever send one AvailRequestSegment. |
AvailRequestSegment
| Name | Type | Description |
|---|---|---|
HotelSearchCriteria |
complex |
Required Specified hotel search criteria. SAP Concur will send only one (1) HotelSearchCriteria. |
StayDateRange |
complex |
Range of dates using ISO 8601. |
TPA_Extensions/SearchSessionToken |
stringLength1to128 |
The token obtained from Search response that links the Search results to Availability and Reservation requests. |
HotelSearchCriteria
| Name | Type | Description |
|---|---|---|
Criterion |
complex |
Required Refer to Criterion in Search. Note that for Rate Details the Criterion will only have one RatePlanCandidate element. |
Criterion
| Name | Type | Description |
|---|---|---|
RatePlanCandidates/RatePlanCandidate |
complex |
Required Specified rate plan candidate. |
RatePlanCandidate
| Name | Type | Description |
|---|---|---|
RatePlanID |
StringLength1to64 |
Required The code that uniquely identifies the rate plan. |
HotelRefs/HotelRef/HotelCode |
stringLength1to16 |
The code that uniquely identifies a single hotel property. The hotel code is decided by vendors. |
HotelRefs/HotelRef/ChainCode |
stringLength1to8 |
The code that identifies a hotel chain or management group. The hotel chain code is decided between vendors. This attribute is optional if the hotel is an independent property that can be identified by the HotelCode attribute. |
StayDateRange
| Name | Type | Description |
|---|---|---|
Start |
date, or time, or datetime |
Required The starting value of the time span. |
End |
date, or time, or datetime |
Required The ending value of the time span. |
RoomStayCandidates
| Name | Type | Description |
|---|---|---|
RoomStayCandidate |
complex |
Required Element used to identify available room products. |
RoomStayCandidate
| Name | Type | Description |
|---|---|---|
GuestCounts |
complex |
Required A collection of guest counts associated with room stay. |
GuestCounts
| Name | Type | Description |
|---|---|---|
GuestCount |
complex |
Required A recurring element that identifies the number of guests and ages of the guests. It currently contains hardcoded values only. See GuestCount below. |
GuestCount
| Name | Type | Description |
|---|---|---|
Count |
integer |
Required SAP Concur only supports one guest. Supported values: 1 |
AgeQualifyingCode |
integer |
Required Supported values: 10 |
Response
The maximum allowed size of OTA_HotelAvailRS is 5 MB. Any response that exceeds this limit shall be dropped.
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
<soap:Body>
<OTA_HotelAvailRS xmlns="http://www.opentravel.org/OTA/2003/05" Version="5">
<Success/>
<RoomStays>
<RoomStay>
<RoomTypes>
<RoomType RoomID="1">
<RoomDescription>
<Text>Test room description.</Text>
</RoomDescription>
</RoomType>
</RoomTypes>
<RatePlans>
<RatePlan RatePlanID="XNFYP4I" AvailabilityStatus="ChangeDuringStay">
<Guarantee GuaranteeType="GuaranteeRequired" />
<CancelPenalties>
<CancelPenalty NoCancelInd="true">
<Deadline AbsoluteDeadline="2017-01-26T18:00:00"/>
<PenaltyDescription>
<Text>Cancellation without penalty allowed before 2017-01-26T18:00:00</Text>
</PenaltyDescription>
</CancelPenalty>
</CancelPenalties>
<MealsIncluded Breakfast="true"/>
<RatePlanDescription>
<Text>Test rate plan description.</Text>
</RatePlanDescription>
</RatePlan>
</RatePlans>
<RoomRates>
<RoomRate RoomID="1" RatePlanID="XNFYP4I">
<RoomRateDescription>
<Text>Basic Wifi Included.</Text>
</RoomRateDescription>
<Rates>
<Rate RateTimeUnit="FullDuration" EffectiveDate="2018-10-26" ExpireDate="2018-10-27">
<PaymentPolicies>
<GuaranteePayment>
<AcceptedPayments>
<AcceptedPayment>
<PaymentCard CardCode="VI"/>
</AcceptedPayment>
</AcceptedPayments>
</GuaranteePayment>
</PaymentPolicies>
<Total AmountAfterTax="199.00" AmountBeforeTax="149.00" CurrencyCode="EUR"/>
<RateDescription>
<Text>Test rate description. Both before and after tax.</Text>
</RateDescription>
</Rate>
<Rate RateTimeUnit="FullDuration" EffectiveDate="2018-10-27" ExpireDate="2018-10-28">
<Total AmountAfterTax="149.00" AmountBeforeTax="99.00" CurrencyCode="EUR"/>
</Rate>
</Rates>
</RoomRate>
</RoomRates>
<TimeSpan End="2018-10-28" Start="2018-10-26"/>
<BasicPropertyInfo ChainCode="ZZ" HotelCode="419430"/>
</RoomStay>
</RoomStays>
<TPA_Extensions RateDetailsInd="true"></TPA_Extensions>
</OTA_HotelAvailRS>
</soap:Body>
</soap:Envelope>
Schema
OTA_HotelAvailRS
| Name | Type | Description |
|---|---|---|
RoomStays |
complex |
Required A collection of details on the room stay including time span of this room stay, and financial information related to the room stay, including guarantee, deposit, payment, and cancellation penalties. |
TPA_Extensions/RateDetailsInd |
boolean |
Always set to true for ratedetails. |
RoomStays
| Name | Type | Description |
|---|---|---|
RoomStay |
complex |
Required Details on the room stay including time span of this room stay, and financial information related to the room stay, including guarantee, deposit, payment, and cancellation penalties. A room stay represents one (1) hotel. |
RoomStay
For a description of the relationship between the RoomID and RatePlanID refer to "Relationship between RoomID and RatePlanID".
| Name | Type | Description |
|---|---|---|
RoomTypes |
complex |
Required Details on the room type. |
RatePlans |
complex |
Required A collection of rate plans associated with a particular room stay. The rate plan element is used to contain all the rate information for a single rate plan Code (example: RACK) for a given date range. A given rate plan may have variable rates, over the effective period of the rate plan, this is represented by the child element rates. |
RoomRates |
complex |
Required List of room rates. |
TimeSpan |
datetimespan |
Required The time span which covers the room stay. The attributes of the OTA DateTimeSpan data type are based on the W3C base data types of timeInstant and timeDuration using ISO 8601. |
BasicPropertyInfo |
complex |
Property Information for the room stay. |
RoomTypes
| Name | Type | Description |
|---|---|---|
RoomType |
complex |
Required Provides details regarding rooms, usually guest rooms. The room description text will be used for each room (defined as a RoomRate) which specifies the same RoomID. |
RoomType
| Name | Type | Description |
|---|---|---|
RoomID |
stringLength1to16 |
Required A string value representing the unique identification of a room if the request is looking for a specific room type. |
RoomDescription |
complex |
Textual information regarding the room. |
RoomDescription
| Name | Type | Description |
|---|---|---|
Text |
string |
Required If multiple text elements are provided, the contents will be concatenated. All text passed is HTML encoded. |
RatePlans
| Name | Type | Description |
|---|---|---|
RatePlan |
complex |
Required Defines the details of the rate plan as used in the booking process. Policies and descriptions that apply to a rate plan. Information significant to defining a rate plan. |
RatePlan
| Name | Type | Description |
|---|---|---|
RatePlanID |
stringLength1to64 |
Required A text field used to indicate a special ID code that is associated with the rate and is essential in the reservation request in order to obtain the rate. Examples: Corporate ID. |
AvailabilityStatus |
stringLength1to32 |
Required Used to specify an availability status for the rate plan. Supported values: AvailableForSale, ChangeDuringStay. |
Guarantee |
complex |
Required Guarantee information that applies to the rate plan. SAP Concur only expects one (1) Guarantee element per RatePlan. |
CancelPenalties |
complex |
Required if RateDetailsInd is true Collection of cancellation penalties. If the cancel penalties are not provided SAP Concur will display: "Cancellation policy not provided by vendor". |
MealsIncluded |
complex |
Defines which meals are included with this rate program. |
RatePlanDescription |
complex |
Textual information regarding the Rate Plan. |
RatePlanDescription
| Name | Type | Description |
|---|---|---|
Text |
string |
Required If multiple text elements are specified, the contents of this element will be rendered as a paragraph. All text passed is HTML encoded. |
Guarantee
| Name | Type | Description |
|---|---|---|
GuaranteeType |
string |
Required The guarantee information to hold a reservation. |
Supported GuaranteeTypes
| GuaranteeType | Description |
|---|---|
Deposit |
In SAP Concur this value is seen as RequiredDeposit. |
DepositRequired |
In SAP Concur this value is seen as RequiredDeposit. |
CC/DC/Voucher |
In SAP Concur this value is seen as RequiredGuarantee. |
PrePay |
In SAP Concur this value is seen as RequiredPrepay. |
None |
In SAP Concur this value is seen as Never. No guarantee is required if user books a room with this type. |
GuaranteeRequired |
RequiredGuarantee. If the Guarantee type cannot be mapped to any accepted type, it will be set to RequiredGuarantee. This value is the default. |
Supported GuaranteeRequired
| GuaranteeRequired | Description |
|---|---|
always |
Guarantee is required all the time independently on deposit account setting. |
never |
Guarantee is never required. |
default |
Guarantee is required if no deposit account is set up. |
CancelPenalties
| Name | Type | Description |
|---|---|---|
CancelPenalty |
complex |
Required Defines the cancellation penalty of the hotel facility. |
CancelPenalty
| Name | Type | Description |
|---|---|---|
NoCancelInd |
boolean |
If true, the reservation cannot be cancelled once the cancellation deadline has expired. False or missing flag will be treated as rate being not cancellable. |
PenaltyDescription |
complex |
Text description of the penalty in a given language. This element may contain a maximum of 9 children text fields. Any excess text elements are dropped. |
Deadline |
complex |
Cancellation deadline. |
PenaltyDescription
| Name | Type | Description |
|---|---|---|
Text |
string |
Required Formatted text content in a given language. All text passed is HTML encoded. |
Deadline
| Name | Type | Description |
|---|---|---|
AbsoluteDeadline |
time or datetime |
Required Defines the absolute deadline in ISO8601 format and in UTC timezone. |
MealsIncluded
| Name | Type | Description |
|---|---|---|
Breakfast |
boolean |
If true, indicates breakfast is included. If false, indicates it is excluded. In both cases this information is shown to a customer in the rate description. The MealsIncluded element must be omitted to avoid any adjustment to the rate description. |
RoomRates
| Name | Type | Description |
|---|---|---|
RoomRate |
complex |
Required Contains the rate details. |
RoomRate
| Name | Type | Description |
|---|---|---|
RoomID |
stringLength1to16 |
Required Room Type ID. The combination of RoomID and RatePlanID must be unique for a RoomStay. |
RatePlanID |
stringLength1to64 |
Required Rate plan ID for which this rate is applicable for. |
Rates |
complex |
Required Contains the rate for the given room. SAP Concur only expects one (1) Rate inside the Rates element if AvailabilityStatus is AvailableForSale. It is optional to include multiple Rate for ChangeDuringStay |
RoomRateDescription |
complex |
The description or name of a room rate. |
Rates
| Name | Type | Description |
|---|---|---|
Rate |
complex |
Required Contains the rate for the given room. Only one (1) Rate element is expected if AvailabilityStatus is AvailableForSale. It is optional to include multiple Rate for ChangeDuringStay |
Rate
| Name | Type | Description |
|---|---|---|
RateTimeUnit |
string |
Indicates the time unit for the rate. Supported values: FullDuration, Day. Default: FullDuration |
EffectiveDate |
date, or time, or datetime |
For ChangeDuringStay. Indicates the start date of the time span. |
ExpireDate |
date, or time, or datetime |
For ChangeDuringStay. Indicates the end date of the time span. |
PaymentPolicies |
complex |
Payment policies for this rate. |
Total |
complex |
Required A description of the rate. |
RateDescription |
complex |
A textual description of a rate. Only one (1) Rate Description element is expected. |
TPA_extensions |
complex |
TPA extensions for a rate. |
RoomRateDescription
| Name | Type | Description |
|---|---|---|
Text |
string |
Required Formatted text content in a given language. All text passed is HTML encoded. |
PaymentPolicies
| Name | Type | Description |
|---|---|---|
GuaranteePayment |
complex |
Element containing the guarantee payment type. |
GuaranteePayment
| Name | Type | Description |
|---|---|---|
AcceptedPayments |
complex |
Required If used, at least one (1) AcceptedPayment should be present. |
AcceptedPayments
| Name | Type | Description |
|---|---|---|
AcceptedPayment |
complex |
Required Accepted payment type. |
AcceptedPayment
| Name | Type | Description |
|---|---|---|
PaymentCard |
complex |
Required Description of payment type. |
PaymentCard
| Name | Type | Description |
|---|---|---|
CardType |
complex |
Required String representation of a card type. Allowed values: AmericanExpress, BankOfAmerica, BritishAirways, CapitalOne, Chase, Citibank, ContinentalAirlines, DeltaAirlines, DiscoverCard, Disney, Eurocard, Hilton, Hyatt, Mariott, Mastercard, RitzCarlton, SouthwestAirlines, StarwoodHotels, UnitedAirlines, USAirways, VISA, Other_. See Code and Description if card type is other_. |
CardType
| Name | Type | Description |
|---|---|---|
Code |
string |
If CardType is Other_, use this attribute for card code. Examples: AX, CA, DC, DS, JC, VI. Map to AMEX, Mastercard, Diners Club, Discover, JCB, Visa |
Description |
string |
If CardType is Other_, use this attribute for card description. |
Total
| Name | Type | Description |
|---|---|---|
AmountBeforeTax |
string |
The total amount not including any associated tax. Examples: sales tax, VAT, GST |
AmountAfterTax |
string |
Required The total amount including all associated taxes. Examples: sales tax, VAT, GST |
CurrencyCode |
alphaLength3 |
Required Currency code. |
RateDescription
| Name | Type | Description |
|---|---|---|
Text |
string |
Required If multiple text elements are provided, the contents will be concatenated. All text passed is HTML encoded. |
Timespan
| Name | Type | Description |
|---|---|---|
Start |
date, time, or datetime |
Required The starting value of the time span. |
End |
date, time, or datetime |
Required The ending value of the time span. |
BasicPropertyInfo
| Name | Type | Description |
|---|---|---|
HotelCode |
complex |
Required Refer to the Property element described in Search. |
Address |
complex |
Refer to Search. |
ContactNumbers |
complex |
Refer to Search. |
Direct Connect - Hotel v2 - Read Itinerary
Read Itinerary
Returns detailed information about a hotel reservation. Used in a process of booking a hotel to write information to Itinerary. Not invoked by user, but by automatic Concur process. Hotel Supplier should reply with HotelRes RS message in the same format, as for HotelResRQ.
| SOAPAction | OTA Name | Message structure |
|---|---|---|
| Read Itinerary | HotelRes | OTA_ReadRQ |
Request
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<authentication xmlns="http://www.concur.com/webservice/auth">
<userid>user</userid>
<password>password</password>
</authentication>
</Header>
<Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<OTA_ReadRQ xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="test_request_id" Version="5.002"
PrimaryLangID="de" AltLangID="de">
<POS>
<Source ISOCurrency="USD">
<RequestorID Type="1" ID="HTL011235"></RequestorID>
</Source>
</POS>
<UniqueID Type="14" ID="88618333"></UniqueID>
</OTA_ReadRQ>
</Body>
</Envelope>
OTA_ReadRQ
| Name | Type | Description |
|---|---|---|
UniqueID |
complex |
Required A reference to identify the booking. |
UniqueID
| Name | Type | Description |
|---|---|---|
Type |
stringLength1to32 |
Required Supported value: 14 |
ID |
stringLength1to32 |
Required UniqueID from HotelResRS is used as reservation ID. |
Response
The response to the Read Itinerary message is the same as the response to the Reservation request, which can be found under Reservation. The response content for cancelled reservations still requires fields marked as Required
Direct Connect - Hotel v2 - Reservation
Reservation Message
Message to reserve a hotel.
| SOAPAction | OTA Name | Message Structure |
|---|---|---|
| book | HotelRes | OTA_HotelResRQ |
- Request
- Schema
- Hotel Reservation
- Room Stays
- Guest Counts
- Guest Count
- Rate Plan
- Guarantee
- Guarantees Accepted
- Payment Card
- Series Code
- Comments
- Comment
- Text
- Res Guest
- Profile
- Customer
- Person Name
- Telephone
- Citizen Country Name
- Company Info
- Res Global Info
- Memberships
- Membership
- Comments
- Comment
- TPA Extensions
- Notify Emails
- Custom Fields
- Custom Field
- Response
Request
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<authentication xmlns="http://www.concur.com/webservice/auth">
<userid>user</userid>
<password>password</password>
</authentication>
</Header>
<Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<OTA_HotelResRQ xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="test_request_id" Version="6"
PrimaryLangID="de" AltLangID="de">
<POS>
<Source ISOCurrency="USD">
<RequestorID Type="1" ID="HTL011235"></RequestorID>
</Source>
</POS>
<HotelReservations>
<HotelReservation>
<RoomStays>
<RoomStay>
<RatePlans>
<RatePlan RatePlanID="ZZZZ1117">
<Guarantee GuaranteeType="CC/DC/Voucher">
<GuaranteesAccepted>
<GuaranteeAccepted>
<PaymentCard CardCode="VI" ExpireDate="1027">
<CardType Code="VI">VISA</CardType>
<CardHolderName>Jane Doe</CardHolderName>
<Address>
<StreetNmbr>600 13TH ST NE</StreetNmbr>
<CityName>WASHINGTON</CityName>
<PostalCode>20002</PostalCode>
<StateProv StateCode="DC">District of Columbia</StateProv>
<CountryName Code="US">United States of America</CountryName>
</Address>
<SeriesCode>
<PlainText>xxx</PlainText>
</SeriesCode>
</PaymentCard>
</GuaranteeAccepted>
</GuaranteesAccepted>
</Guarantee>
</RatePlan>
</RatePlans>
<TimeSpan Start="2017-01-26" End="2017-01-27"></TimeSpan>
<BasicPropertyInfo HotelCode="111222"></BasicPropertyInfo>
<Comments>
<Comment>
<Text TextFormat="PlainText">ROLLAWAY</Text>
</Comment>
<Comment>
<Text TextFormat="PlainText">FOAMPILLOWS</Text>
</Comment>
</Comments>
</RoomStay>
</RoomStays>
<ResGuests>
<ResGuest>
<Profiles>
<ProfileInfo>
<Profile>
<Customer Gender="Female" BirthDate="1987-05-12">
<PersonName Language="de">
<NamePrefix>MRS</NamePrefix>
<GivenName>JANE</GivenName>
<Surname>DOE</Surname>
</PersonName>
<Telephone PhoneNumber="703-555-6100"></Telephone>
<Email>jane.doe@example.com</Email>
<Address>
<AddressLine>209 Madison St Suite 400</AddressLine>
<CityName>Alexandria</CityName>
<PostalCode>22314</PostalCode>
<StateProv StateCode="VA"></StateProv>
<CountryName Code="US">United States of America</CountryName>
</Address>
<CitizenCountryName Code="US"></CitizenCountryName>
</Customer>
<CompanyInfo>
<CompanyName>SAP Concur</CompanyName>
</CompanyInfo>
</Profile>
</ProfileInfo>
</Profiles>
<GuestCounts>
<GuestCount Count="1"></GuestCount>
</GuestCounts>
</ResGuest>
</ResGuests>
<ResGlobalInfo>
<Memberships>
<Membership ProgramCode="HotelLoyaltyProgram" AccountID="1111111"></Membership>
</Memberships>
</ResGlobalInfo>
<TPA_Extensions>
<SearchSessionToken>5EA6C45E55104704E4</SearchSessionToken>
</TPA_Extensions>
</HotelReservation>
<TPA_Extensions>
<NotifyEmails>
<NotifyEmails>jane.doe@example.com</NotifyEmails>
<NotifyEmails>arranger@example.com</NotifyEmails>
<NotifyEmails>manager@example.com</NotifyEmails>
</NotifyEmails>
<CustomFields>
<CustomField Name="trip1" Value="value1t"></CustomField>
<CustomField Name="trip2" Value="value2t"></CustomField>
<CustomField Name="user1" Value="value1u"></CustomField>
<CustomField Name="user2"></CustomField>
</CustomFields>
</TPA_Extensions>
</HotelReservations>
</OTA_HotelResRQ>
</Body>
</Envelope>
OTA_HotelResRQ
| Name | Type | Description |
|---|---|---|
HotelReservations |
complex |
Required A collection of hotel reservations. SAP Concur will only send one (1) hotel reservation. |
HotelReservation
| Name | Type | Description |
|---|---|---|
RoomStays |
complex |
Required A reference to identify the booking. |
ResGuests |
complex |
Required List of guests. Supported value: 1 |
ResGlobalInfo |
complex |
Contains information that affects the reservation as a whole, typically a list of reward programs (see Memberships) or itinerary remarks (see Comments). |
TPA_Extensions/SearchSessionToken |
stringLength1to128 |
The token obtained from Search response that links the Search results to Availability and Reservation requests. |
RoomStays
| Name | Type | Description |
|---|---|---|
RatePlans |
complex |
Required Refer to RatePlans in Availability. |
Timespan |
complex |
Required Refer to Time-span in Availability. |
BasicPropertyInfo |
complex |
Required See Availability. |
Comments |
complex |
Comments from the user which are passed on to the hotel. |
GuestCounts
| Name | Type | Description |
|---|---|---|
GuestCounts |
complex |
Required Please note: this field is currently being discussed with our partners as the plan to remove GuestCounts from OTA_HotelAvailRQ. A recurring element that identifies the number of guests. |
GuestCount
| Name | Type | Description |
|---|---|---|
Count |
integer |
Required Please note: this element is planned to be removed. A recurring element that identifies the number of guests and ages of the guests. The number of guests. Supported value: 1 |
RatePlan
| Name | Type | Description |
|---|---|---|
RatePlanID |
stringLength1to64 |
A text field used to provide a special ID code that is associated with the rate and is required in the reservation request in order to obtain the rate. |
Guarantee |
complex |
Required Refer to Guarantee in Availability. |
Guarantee
| Name | Type | Description |
|---|---|---|
GuaranteeType |
stringLength1to32 |
Required CC/DC/Voucher will be sent if credit card present, None otherwise. |
GuaranteesAccepted |
complex |
Required Guarantee and payment information. |
GuaranteesAccepted
| Name | Type | Description |
|---|---|---|
Default |
boolean |
This is to indicate that the information in the model is the default (e.g. if PaymentCard information is completed then this would be considered the default if the boolean is true). |
NoCardHolderInfoReqInd |
boolean |
If true, no credit card holder information is required. If false, it is required. |
NameReqInd |
boolean |
If true, the credit card holder name is required. If false, it is not required. |
AddressReqInd |
boolean |
If true, credit card holder address is required. If false, it is not required. |
PhoneReqInd |
boolean |
If true, credit card holder phone number is required. If false, it is not required. |
InterbankNbrReqInd |
boolean |
If true, the credit card interbank number is required. If false, it is not required. |
PaymentCard |
complex |
Required Specific payment card information. |
PaymentCard
| Name | Type | Description |
|---|---|---|
CardCode |
upperCaseAlphaLength1to2 |
Issuer code. Example: AX, CA, DC, DS, JC, VI. Map to AMEX, Mastercard, Diners Club, Discover, JCB, Visa |
ExpireDate |
MMYYDate |
Indicates the ending date. |
CardType |
stringLength1to32 |
Required Payment card type. Example: MasterCard |
CardHolderName |
stringLength1to32 |
Required Card holder name. |
CardNumber |
complex |
Required The card number. |
Address |
complex |
Required Refer to Address in Search. |
SeriesCode |
complex |
Verification digits. |
SeriesCode
| Name | Type | Description |
|---|---|---|
PlainText |
stringLength1to32 |
Required CVV number. Only one (1) element of this type is sent. |
Comments
| Name | Type | Description |
|---|---|---|
Comment |
complex |
Required SAP Concur will send one Text element per Comment element. |
Comment
| Name | Type | Description |
|---|---|---|
Text |
string |
Required Text representing the comment. |
Text
| Name | Type | Description |
|---|---|---|
TextFormat |
stringLength1to32 |
Required Supported value: Plain text |
ResGuest
| Name | Type | Description |
|---|---|---|
Profiles |
complex |
Required List of Profiles. SAP Concur will only send one (1) profile. |
Profile
| Name | Type | Description |
|---|---|---|
Customer |
complex |
Required Element to describer a customer. |
CompanyInfo |
complex |
Element to capture the company name. |
Customer
| Name | Type | Description |
|---|---|---|
Gender |
string |
Gender. Supported values: Male, Female, Unknown, Male_NoShare, Female_NoShare |
BirthDate |
date |
Customer's birthday. |
PersonName |
complex |
Element representing a customer's name. |
Telephone |
complex |
Element representing a telephone number. |
Email |
stringLength1to128 |
Email address. |
Address |
complex |
Refer to Address in Search. |
CitizenCountryName |
complex |
ISO 3166 representation of the user's country as defined in their SAP Concur Profile. |
PersonName
| Name | Type | Description |
|---|---|---|
NamePrefix |
stringLength1to16 |
Salutation of honorific. List subject to change. Example values: Mr, Mrs, Ms, Miss, Dr, Rev, Sir, Lord, Lady, Dr Mr, Dr Mrs, Dr Ms, Prof Mr, Prof Mrs, Prof Ms, Prof Dr Mr, Prof Dr Mrs, Prof Dr Ms. Note: Prefixes can be specified in any of the languages supported by Concur Travel. |
GivenName |
stringLength1to64 |
Given name, first name or names. |
Surname |
stringLength1to64 |
Required Family name, last name. May also be used for full name if the sending system does not have the ability to separate a full name into its parts. Example: the surname element may be used to pass the full name. |
Telephone
| Name | Type | Description |
|---|---|---|
PhoneNumber |
stringLength1to32 |
Required A string representing a customer's phone number. |
CitizenCountryName
| Name | Type | Description |
|---|---|---|
Code |
stringLength1to32 |
Required ISO 3166 country code. |
CompanyInfo
| Name | Type | Description |
|---|---|---|
CompanyName |
stringLength1to32 |
Required A string representing a customer's company. |
ResGlobalInfo
Note: This structure is used in both request and response. Different elements are used in each of them.
| Name | Type | Description |
|---|---|---|
Memberships |
complex |
Request Only A collection of memberships. Provides a list of reward programs. Example: loyalty cards |
Comments |
complex |
Response Only A collection of comments. Provides a list of arbitrary reservation comments. Example: modification code |
BasicPropertyInfo |
complex |
See Availability. |
Memberships
| Name | Type | Description |
|---|---|---|
Membership |
complex |
A recurring element that identifies the type of reservation comment. |
Membership
| Name | Type | Description |
|---|---|---|
ProgramCode |
stringLength1to32 |
Required Always HotelLoyaltyProgram for hotels |
AccountID |
stringLength1to64 |
Required The account identification number for this particular member in this particular program. |
Comments
| Name | Type | Description |
|---|---|---|
Comment |
complex |
A recurring element that carries reservation comment. Maximum elements: 9 |
Comment
| Name | Type | Description |
|---|---|---|
Name |
stringLength1to64 |
Attribute containing comment title. |
Text |
string |
Required Comment payload. Up to 3 Text elements in the comment. Up to 200 characters in the text. |
TPA Extensions
| Name | Type | Description |
|---|---|---|
NotifyEmails |
complex |
Email address which can be used by the vendor to contact the customer. |
CustomFields |
complex |
A reference to identify the booking. |
NotifyEmails
| Name | Type | Description |
|---|---|---|
NotifyEmails |
stringLength1to128 |
Required There will be one (1) NotifyEmails element per email address in the configuration. |
CustomFields
| Name | Type | Description |
|---|---|---|
CustomField |
complex |
Required A custom field in the form of a key-value pair. |
CustomField
| Name | Type | Description |
|---|---|---|
Name |
stringLength1to32 |
Required Name of the custom field. |
Value |
stringLength1to32 |
Value of the custom field. |
Response
The maximum allowed size of OTA_HotelResRS is 150 KB. Any response that exceeds this limit shall be dropped.
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
<soap:Body>
<OTA_HotelResRS xmlns="http://www.opentravel.org/OTA/2003/05" Version="6" ResResponseType="Reserved">
<Success/>
<HotelReservations>
<HotelReservation>
<UniqueID Type="14" ID="88618333"/>
<UniqueID Type="1000" ID="12345"/>
<RoomStays>
<RoomStay>
<RatePlans>
<RatePlan RatePlanID="EZ57LL7">
<CancelPenalties CancelPolicyIndicator="true">
<CancelPenalty>
<PenaltyDescription>
<Text>test cancel policy 1</Text>
</PenaltyDescription>
</CancelPenalty>
<CancelPenalty>
<PenaltyDescription>
<Text>test cancel policy 2</Text>
</PenaltyDescription>
<PenaltyDescription>
<Text>test cancel policy 3</Text>
</PenaltyDescription>
</CancelPenalty>
<CancelPenalty>
<Deadline AbsoluteDeadline="2017-01-26T18:00"/>
</CancelPenalty>
</CancelPenalties>
</RatePlan>
</RatePlans>
<RoomRates>
<RoomRate>
<Rates>
<Rate>
<Total AmountAfterTax="185.00" AmountBeforeTax="85.00" CurrencyCode="EUR"/>
</Rate>
</Rates>
</RoomRate>
</RoomRates>
<TimeSpan End="2017-01-27" Start="2017-01-26"/>
<BasicPropertyInfo HotelCode="50709" HotelName="Alexander Plaza">
<Address>
<AddressLine>Rosenstr. 1</AddressLine>
<CityName>Berlin</CityName>
<CountryName Code="DEU">Federal Republic of Germany</CountryName>
<StateProv StateCode="BE">Berlin District</StateProv>
<PostalCode>BE123</PostalCode>
</Address>
<ContactNumbers>
<ContactNumber PhoneNumber="1111111112" PhoneTechType="1"/>
</ContactNumbers>
</BasicPropertyInfo>
</RoomStay>
</RoomStays>
<ResGuests>
<ResGuest>
<Profiles>
<ProfileInfo>
<Profile>
<Customer>
<PersonName>
<GivenName>Jane</GivenName>
<Surname>Doe</Surname>
</PersonName>
</Customer>
</Profile>
</ProfileInfo>
</Profiles>
</ResGuest>
</ResGuests>
<ResGlobalInfo>
<Comments>
<Comment Name="First Comment">
<Text>First line of first comment</Text>
<Text>Second line of first comment</Text>
</Comment>
<Comment>
<Text>Second comment without name</Text>
</Comment>
</Comments>
</ResGlobalInfo>
</HotelReservation>
</HotelReservations>
</OTA_HotelResRS>
</soap:Body>
</soap:Envelope>
OTA_HotelResRS
| Name | Type | Description |
|---|---|---|
ResResponseType |
stringLength1to32 |
Required See the list of possible values. |
HotelReservations |
complex |
Required SAP Concur only supports one (1) reservation. All extra reservations will be ignored. |
ResResponseType
| Value | Description |
|---|---|
Cancelled |
The item is cancelled. |
Committed |
The item is reserved. |
Unsuccessful |
- |
Reserved |
The item is reserved. |
HotelReservations
| Name | Type | Description |
|---|---|---|
HotelReservation |
complex |
Required A reference to identify the booking. |
HotelReservation
| Name | Type | Description |
|---|---|---|
UniqueID |
complex |
Required A reference to identify the booking. Maximum occurrences: 2 |
RoomStays |
complex |
Required A collection of details on the room stay including time span of this room stay, and financial information related to the room stay, including guarantee, deposit, payment, and cancellation penalties. |
UniqueID
| Name | Type | Description |
|---|---|---|
ID |
stringLength1to32 |
Required A reference to identify the booking. |
Type |
stringLength1to32 |
Required A reference to identify the type of UniqueID. See Type. |
Type - Possible Values
| Value | Description |
|---|---|
14 |
Reservation ID used in subsequent calls (Itinerary, Cancel). |
15 |
Cancellation number, displayed in UI, proof of cancellation. |
40 |
Hotel Reservation System Confirmation number (for future use). |
1000 |
Cancellation/modification code. This will be rendered on itinerary page and can be used to change the reservation outside of the SAP Concur system. SAP Concur-specific OTA extension. |
RoomStays
| Name | Type | Description |
|---|---|---|
RoomStay |
complex |
Required Details on the room stay including time span of this room stay, pointers to res guests, comments and special requests pertaining to this particular room stay. Financial information related to the room stay, including guarantee, deposit, payment, and cancellation penalties. |
RoomStay
| Name | Type | Description |
|---|---|---|
RatePlans |
complex |
Required A collection of rate plans associated with a particular room stay. |
Timespan |
complex |
Required Refer to TimeSpan in Availability. |
BasicPropertyInfo |
complex |
Required See Availability. |
RatePlan
| Name | Type | Description |
|---|---|---|
CancelPenalties |
complex |
Refer to CancelPenalties in Availability. |
RoomRates
| Name | Type | Description |
|---|---|---|
RoomRate |
complex |
Required RoomRate used for reservation. SAP Concur only expects one (1) RoomRate. |
RoomRate
| Name | Type | Description |
|---|---|---|
Rates |
complex |
Required SAP Concur only expects one (1) Rates. |
Rates
| Name | Type | Description |
|---|---|---|
Rate |
complex |
Required Contains the payment policy for the given room. SAP Concur only expects one (1) Rate. |
Rate
| Name | Type | Description |
|---|---|---|
Total |
complex |
Required A description of the rate. Refer to Total in Availability. |
Direct Connect - Hotel v2 - Search
Search
Message to perform the initial search for hotels.
| SOAPAction | OTA Name | Message Structure |
|---|---|---|
| search | HotelSearch | OTA_HotelSearchRQ |
Request
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<authentication xmlns="http://www.concur.com/webservice/auth">
<userid>user</userid>
<password>password</password>
</authentication>
</Header>
<Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<OTA_HotelSearchRQ xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="test_request_id" Version="4"
PrimaryLangID="de" AltLangID="de" MaxResponses="100">
<POS>
<Source ISOCurrency="USD">
<RequestorID Type="1" ID="HTL011235"></RequestorID>
</Source>
</POS>
<Criteria>
<Criterion>
<Position Latitude="47.61037" Longitude="-122.20067"></Position>
<HotelRef HotelName="sunshine"></HotelRef>
<Radius Distance="5" DistanceMax="30" UnitOfMeasureCode="1"></Radius>
<StayDateRange Start="2018-09-26" End="2018-09-27"></StayDateRange>
</Criterion>
</Criteria>
<TPA_Extensions>
<CustomFields>
<CustomField Name="OrgUnit" Value="Travel Agents"></CustomField>
</CustomFields>
</TPA_Extensions>
</OTA_HotelSearchRQ>
</Body>
</Envelope>
OTA_HotelSearchRQ
| Name | Type | Description |
|---|---|---|
MaxResponses |
integer |
Required SAP Concur currently supports 100 search results in one (1) message. If more than 100 results are returned SAP Concur drops all results after the 100th entry. |
Criteria |
complex |
Required Specified hotel search criteria. |
TPA_Extensions |
complex |
This adds an Org Unit name to the Search request. |
Criteria
| Name | Type | Description |
|---|---|---|
Criterion |
complex |
Required Child elements that identify a single search criterion by criteria type. |
Criterion
The criterion is used to define the search criteria. Currently we support only one Criterion.
| Name | Type | Description |
|---|---|---|
Position |
complex |
Required for Search request only, but optional for Availability request. Used to specify the geographic coordinates of a location, expressed in notation specified by ISO standard 6709. |
HotelRef |
complex |
Indicates the detail of hotel reference information. |
Radius |
complex |
Used to specify the extent of a search area. The extent is relative to an element (position, address, hotelRef, etc.) present in this ItemSearchCriterionType that specifies a location. |
StayDateRange |
complex |
Required Range of dates using ISO 8601. |
TPA_Extensions
| Name | Type | Description |
|---|---|---|
CustomFields |
complex |
This adds Org Unit name. |
CustomFields
| Name | Type | Description |
|---|---|---|
CustomField |
- | - |
Name |
xs:string |
- |
Value |
xs:string |
- |
Position
| Name | Type | Description |
|---|---|---|
Latitude |
stringLength1to16 |
Required The measure of the angular distance on a meridian north or south of the equator. |
Longitude |
stringLength1to16 |
Required The measure of the angular distance on a meridian east or west of the prime meridian. |
HotelRef
| Name | Type | Description |
|---|---|---|
HotelName |
stringLength1to128 |
A text field used to communicate the proper name of the hotel. |
Radius
The radius element is used along with the Hotel Preference to categorize the search results.
| Name | Type | Description |
|---|---|---|
Distance |
stringLength1to16 |
Required The distance from a reference point. |
DistanceMax |
stringLength1to16 |
Attribute indicating the distance from a reference point or Preferred (Corporate) hotels. |
UnitOfMeasureCode |
stringLength1to16 |
Required The unit of measure in a code format. Refer to OpenTravel Code List of Measure Code (UOM). SAP uses 1 for miles, 2 for kilometers. |
StayDateRange
| Name | Type | Description |
|---|---|---|
Start |
date, time, or datetime |
Required The starting value of the time span. |
End |
date, time, or datetime |
Required The ending value of the time span. |
Response
The maximum allowed size of OTA_HotelSearchRS is 1 MB. Any response that exceeds this limit will be dropped.
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
<soap:Body>
<OTA_HotelSearchRS xmlns="http://www.opentravel.org/OTA/2003/05" AltLangID="EN" PrimaryLangID="EN" Version="4">
<Success/>
<Properties>
<Property ChainCode="HI" ChainName="Holiday Inn" HotelCode="22222" HotelName="Holiday Inn Express Sunshine">
<Position Latitude="47.61038" Longitude="-122.20068"/>
<Address>
<AddressLine>99 East 27th Street</AddressLine>
<CityName>Bellevue</CityName>
<PostalCode>98009</PostalCode>
<StateProv StateCode="WA">Washington</StateProv>
<CountryName Code="US">United States of America</CountryName>
</Address>
<ContactNumbers>
<ContactNumber PhoneNumber="+14255551234" PhoneTechType="1"/>
</ContactNumbers>
<Award Rating="4"/>
<HotelAmenity Code="173"/>
<HotelAmenity Code="255"/>
<TPA_Extensions>
<HotelPreference>not_preferred</HotelPreference>
<TPA_HotelPreviewImageURI>
<URL>https://production.example.com/hotel-image.jpg</URL>
</TPA_HotelPreviewImageURI>
<TPA_PropertyReferenceInfo>
<PropertyReference ReferenceCatalogCode="1376249" ReferenceCatalogName="giata"/>
</TPA_PropertyReferenceInfo>
</TPA_Extensions>
</Property>
</Properties>
<TPA_Extensions>
<SearchSessionToken>5EA6C45E55104704E4</SearchSessionToken>
</TPA_Extensions>
</OTA_HotelSearchRS>
</soap:Body>
</soap:Envelope>
OTA_HotelSearchRS
| Name | Type | Description |
|---|---|---|
Properties |
complex |
Required A collection of individual property information. |
TPA_Extensions/SearchSessionToken |
stringLength1to128 |
Optional A token that links the Search results to Availability and Reservation requests. |
Properties
| Name | Type | Description |
|---|---|---|
Property |
complex |
Required A property that matches some or all of the search criteria. |
Property
| Name | Type | Description |
|---|---|---|
ChainCode |
stringLength1to8 |
2-letter valid GDS chain code. The code that identifies a hotel chain or management group. Must be present to support filtering, preferences or travel rules base on chains |
ChainName |
stringLength1to64 |
The name of the hotel chain. Examples: Hilton, Marriott, Hyatt, Starwood |
HotelCode |
stringLength1to16 |
Required The code that uniquely identifies a single hotel property. Used in other OTA messages. |
HotelName |
stringLength1to128 |
Required A text field used to communicate the proper name of the hotel. |
Position |
complex |
Required Refer to Position in the Request. |
Address |
complex |
Required Public address of the hotel property. |
ContactNumbers |
complex |
Property contact numbers. |
Award |
complex |
An element that identifies the hotel rating. |
HotelAmenity |
complex |
List of hotel amenities. |
TPA_Extensions |
complex |
SAP Concur-specific extension of OTA spec. This adds support for extra property fields. |
Address
| Name | Type | Description |
|---|---|---|
AddressLine |
stringLength1to255 |
The street name and number. Maximum occurrences: 5 |
CityName |
stringLength1to64 |
Name of the city. |
PostalCode |
stringLength1to16 |
The postal code. |
StateProv |
complex |
Name of the state. |
CountryName |
complex |
Country name. Example: Ireland |
StateProv
| Name | Type | Description |
|---|---|---|
StateCode |
stringLength0to64 |
The standard code or abbreviation for the state, province, or region (note the code may not be available for all states). |
CountryName
| Name | Type | Description |
|---|---|---|
Code |
stringLength0to64 |
Required The name or ISO 3166 code of a country. |
ContactNumbers
| Name | Type | Description |
|---|---|---|
ContactNumber |
complex |
Element which contains the ContactNumber. SAP Concur only accepts the first (1) ContactNumber of each supported type. |
ContactNumber
| Name | Type | Description |
|---|---|---|
CountryAccessCode |
stringLength1to32 |
The country code. |
PhoneNumber |
stringLength1to32 |
Required The phone number. |
PhoneTechType |
string |
SAP Concur currently only supports a PhoneTechType set to 1 (phone) or 3 (fax). You can omit this field only in case you are providing one contact number. We suggest to fill the type in all cases, it may become mandatory in the future. |
Award
| Name | Type | Description |
|---|---|---|
Rating |
integer |
Required Hotel rating should be an integer number from 0 to 5, representing its star rating. A rating value of 0 will be ignored and treated as N/A. |
HotelAmenity
| Name | Type | Description |
|---|---|---|
Code |
string |
Refer to Supported Hotel Amenities |
Supported Hotel Amenities
| Code | Description |
|---|---|
173 |
Breakfast |
255 |
Broadband Internet |
228 |
Business Center |
215 |
Convention Center |
96 |
Dry Cleaning |
48 |
Fitness Center |
44 |
Game Room |
236 |
Golf Course |
54 |
Indoor Pool |
289 |
Kids Activities |
269 |
Meeting Rooms |
198 |
Non-smoking Rooms |
66 |
Outdoor Pool |
224 |
Pets Allowed |
76 |
Restaurant |
71 |
Swimming Pool |
233 |
Tennis Court |
101 |
Wheelchair Accessible |
TPA Extensions
| Name | Type | Description |
|---|---|---|
HotelPreference |
stringLength1to32 |
Required SAP Concur allows customers to override property preference in the system settings. Supported values: not_preferred, less_preferred, preferred, most_preferred |
TPA_HotelPreviewImageURI |
complex |
Required Details for an image of a given category. |
TPA_PropertyReferenceInfo |
complex |
Alternate property ID. Required for Corporate Discount Note support |
TPA_HotelPreviewImageURI
| Name | Type | Description |
|---|---|---|
URL |
string |
Required Contains an HTTPS URL pointing to a .png or .jpg hotel image file. SAP Concur supports one image URL in the Search Response. For the ability to display more images refer to Descriptive Info message. The image will be used as a thumbnail and should be limited to 70x70 pixels to prevent image artifacts by scaling. |
TPA_PropertyReferenceInfo
| Name | Type | Description |
|---|---|---|
ReferenceCatalogName |
string |
Required which catalog the property reference comes from. Support giata only for now |
ReferenceCatalogCode |
string |
Required alternate property id (only giata id of hotel for now) from specified reference catalog |
Direct Connect - Hotel v2 - Update History
History of changes in HS2 developer documentation
| Date of Change | Description |
|---|---|
| July 22, 2021 | Remove references to RefPoint in the Search criteria, it is not used. |
| July 21, 2021 | Removing required tag on Avail/RequireSeriesCode. Removing mention of RequireSeriesCode on RateDetails. |
| June 23, 2021 | More details on ReadItin response and fix to Rate/ExpireDate on RateDetails. |
| May 17, 2021 | Update description for Reservation response confirmation number of type 40 to specify Hotel reservation number. |
| May 7, 2021 | Add response time and content length expectations to Intro page. Add RequestorID to examples for consistency. |
| Apr 23, 2021 | Correcting examples to remove elements/attributes that are not supported. Adding clarification for Reservation.PersonName.NamePrefix. Adding examples of usage for StateProv element. Clarifying expectations for imageURLs in Seach and DescriptiveInfo |
| Mar 19, 2021 | Remove mention of content not being accessible to mobile app. Correction to Availability RoomTypes description. Correction to RoomDescription to indicate multiple text elements are accepted. Removed mention of offset attribute as option for AbsoluteDeadline |
| Mar 16, 2021 | Clarify what value is sent in GuaranteeType in Reservation Request |
| Feb 16, 2021 | New node TPA Property Reference Info added to the Search Response. Description update to clarify that what value is sent in HotelLoyaltyProgram is always sent as ProgramCode in Memberbship |
| Feb 8, 2021 | Remove PaymentPolicies in Reservation Response. Change type Text to string in Descriptive Information Response. Change type and description of Text under RatePlanDescription in Availability and Rate Details Response. |
| Jan 29, 2021 | Clarify NamePrefix in Reservation Request. Make PaymentPolicies in Reservation Response optional |
| Jan 27, 2021 | Update Deadline under CancelPenalty to optional node. Update AbsoluteDeadline attribute under Deadline to required. Update type of URL in TPA_HotelPreviewImageURI to string. |
| Jan 11, 2021 | formattedText type is replaced with string. No longer accepts Deadline node under Guarantee in Availability and Rate Details. Updated ImageFormat's URL type. Updated RateId and RatePlanId type. Added description of RoomRates in Reservation. AmountBeforeTax is now optional in Availability and Rate Details. |
| Dec 15, 2020 | Added BasicPropertyInfo and Timespan to Reservation Response Docs |
| Dec 4, 2020 | Clarification of NoCancelInd and Absolute Deadline in CancelPenalty, Rate-Details and Availability |
Direct Connect - Hotel v2 - Use Cases
Basic scenario encompassing all the functionality provided by Hotel Service 2 incorporated into Concur Travel starting from a hotel search, through to confirmation of a booking and ending with a cancellation.
Actors
- Primary Actor - Business traveler
- Secondary Actor - Hotel Supplier
Use Case
Business traveler performs a search for hotels given a criteria.
The UI displays the available hotels. The business traveler can then select a hotel with visible rates or request to View Rooms in case they are not present. The Business traveler selects a hotel with rates.
The UI displays all available rates for the chosen hotel. The Business user can see the Cancellation Policy. The business traveler clicks on Hotel Details.
The UI displays the hotel details including a long description. The Business traveler closes the Hotel Details pop-up
The UI displays all available rates for the chosen hotel. The business traveler clicks on Rules and Cancellation Policy.
The UI displays the Rules and the Cancellation Policy for the chosen hotel. The Business Travel closes the Rules and Cancellation Policy pop-up.
The UI displays all available rates for the chosen hotel. The Business traveler selects the top most rate. The Trip Summary page is displayed where the Business traveler can set the Hotel Preferences, Enter Guest information (from their profile), select the method of payment and view the total estimated price. The Business traveler agrees to the hotel's rate rules, restrictions and cancellation policy and clicks Reserve Hotel and Continue.
The UI shows the Trip Details page where the Business traveler can add items to their itinerary and review the current itinerary. The Business traveler clicks Next.
The UI shows the Trip Booking Information page where the Business traveler can add trip details. The Business traveler clicks Next.
The UI shows the Trip Confirmation page where the Business traveler can confirm the booking on cancel it. The Business traveler clicks Confirm Booking.
The UI shows the Finished page where the Business traveler can review the trip overview and see the confirmation number along with the trip locator.
The Business user can view the trip in the Upcoming Trips tab on the main Travel page. The Business traveler clicks on the Trip name.
The UI shows the Trip Overview page. The Business traveler chooses the cancel the hotel reservation, by clicking cancel.
The UI shows the Cancel Trip pop-up where the Business traveler may chooser to enter a comment. The Business traveler clicks OK.
The UI shows the Rules and cancellation policy. The Business traveler accepts the policies by checking the 'I agree ...' button and clicking Continue
The UI shows the trip cancellation page where confirmation and cancellation numbers can be found. The Business traveler closes the pop-up.
Search Criteria
Given the following example:
<RadiusDistance="5" DistanceMax="30" UnitOfMeasureCode="2">
Out of 100 returned hotels in response from the Hotel Supplier first 10 hotels are Most Preferred hotels within the 30km radius. The next 10 hotels are Preferred hotels from 30km radius. The remaining 80 hotels are hotels with no preference within the 5km radius. Note: The preference level is defined by the HotelPreference element in the TPA_Extensions, which is outlined in Search.
Reservation and Read Requests
SAP Concur will follow up a Reservation Request with a Read request as soon as possible after processing the Reservation Response. If a Read request does not arrive within 5 minutes for a given Reservation, then the supplier should treat that Reservation as an orphan and should thus seek to cancel it.
General System Overview

Direct Connect - Hotel v2 - Virtual Payment Solution
The goal of this document is to establish the flow for virtual / alternative payment methods in conjunction with booking hotels via Concur’s hotel API (HS2). While doing so, it seeks to minimize complexity of implementation that often arises when configuration work needs to be done on both ends (Concur and supplier side). Since the payment solution is typically handled on suppliers’ side, the supplier should control which form of payment will be made available in Concur for each specific client and property by passing the form of payment to Concur. Concur will then offer the accepted payment method to users in the booking flow.
SETUP ON HOTEL SUPPLIER SIDE
The payment agreement is typically made with the hotel supplier. There are multiple potential options which could be:
- AirPlus Company Account or Amex BTA payment
- Virtual card payment e.g. Amex vPay or AirPlus AIDA
- Central Billing or billback agreements
All mentioned payment methods are normally set up on hotel supplier side to ensure the payment method will be part of the reservation to the hotel and to guarantee acceptance at the hotel. Furthermore, the hotel supplier takes care of invoicing.
SETUP ON CONCUR SIDE
To make sure that the user can use the payment option that is set up on hotel supplier side the client needs to be identified at hotel supplier side. This happens with a client ID (Requestor ID). Requestor ID needs to be set up in Concur on a company (configuration) level.
BOOKING FLOW
1. Search request
Requestor ID is sent with OTA_HotelSearchRQ. Requestor IDs can only be supported on travel configuration level.
2. Response from hotel supplier in OTA_HotelAvailRS
Virtual payment will be marked by the hotel supplier under Concur’s Availability endpoint, OTA_HotelAvailRS (as documented in the SAP Concur Developer Center for Direct Connect: Hotel Service 2). The element to be used will be ‘GuaranteeType’ and its value should be set to ‘none’.
3. Display of payment options in Concur on Review and Reserve page
When guarantee type is set to ‘none’ the FOP selection will not be triggered in the Review and Reserve page, allowing the user to proceed with the reservation without having to specify a payment method.

4. Descriptive Billing Data
For Company Account payment or virtual payment, descriptive billing data is required. Descriptive billing data is typically profile data (e.g. cost center or employee ID) or custom trip fields (e.g. project number). Those fields need to be mapped to reference data fields in Concur so that it can be sent to the hotel supplier with the reservation. In order to have this data passed in the reservation request, it is required to have them displayed at the start of booking. Descriptive billing data can be transmitted independently from the payment solution set up at hotel supplier. The field names can be individually defined by HotelService supplier. A client individual naming of custom fields will not be supported.
Org units can also be integrated in this workflow. If enabled, they will be made available through our OTA_HotelSearchRQ and OTA_HotelResRQ call.
5. Reservation
After the user has selected a rate with GuaranteeType marked as ‘none’ the reservation request will be sent with OTA_HotelResRQ. The OTA_HotelResRQ also contains descriptive billing information.
Direct Connect - Hotel v2 - XSD schema
Current xsd schema for Hotel Service 2
ESS
Event Subscription Service v4
- Overview
- Scope Usage
- Process Flow
- Access Control
- Delivery Model
- Endpoint Requirements
- Authentication
- Service Behavior
ESS Overview
The Event Subscription Service (ESS) implements the Publish/Subscribe pattern using principles of Event Driven Architecture in the SAP Concur platform. It allows clients and partners to be notified through web services when certain actions take place in connected companies. When the business/system event occurs ESS sends that event to the configured endpoint with relevant information.
- Event - a state of a business/system object or entity. Always has an
EventTypethat represents a type of entity change or specific state in a workflow. Example: Report Created, Report Submitted, etc. - Topic - a stream of events of business/system object or entity. Example:
concur.user,concur.expense.report,concur.travel.request. - Subscription - a topic consumer. Each subscription has a topic it is subscribed to.
- Webhook - an ESS application that uses a subscription model and delivers events to the endpoint.
In order to begin receiving events, you must first subscribe to the relevant topic(s) for your application. To subscribe to an event, you must work with your relevant SAP Concur technical contact; for partners, please work with your technical enablement contact. For customers, your web services consultant will subscribe on your behalf to the relevant topic(s).
Scope Usage
There are two levels of scopes required for creating subscription.
| Name | Description | Endpoint |
|---|---|---|
events.topic.read |
Access to ESS API | GET, POST, PUT, DELETE |
%topic scope% |
Access to specific topic (events) | GET, POST, PUT, DELETE |
- If application has only the
events.topic.readscope an empty list of topics will always be returned.
Process Flow

Access Control
ESS requires a caller to have a proper JWT and scopes, for more details please see the Scopes documentation. A caller must have the following types of scopes:
- The ESS API level scope
events.topic.readis required to be able to access ESS API. - A resource level scope, for example
expense.request.readis required to be able to access theexpense.requesttopic and to be able to create subscriptions to that topic.
All required scopes can be requested for a caller application by Partner Enablement team.
ESS Delivery Model
It is important to remember that ESS doesn't have an API that you can call for events, ESS delivers events to your endpoint.
- It uses an outbound callout where the SAP Concur offering calls a public facing URL provided by client or partner, which is a web server hosted by the third-party developer or client.
- The application endpoint can also use the related web services to retrieve or send SAP Concur data. For example, an event may be generated when a request for travel is submitted. The application endpoint may then leverage data from the event, such as the request ID, to retrieve the relevant travel request record from the published Request APIs.
Endpoint Requirements
ESS guarantees at least once event delivery. This is accomplished through the retry posting the event payload to the subscribers' endpoint until the response indicates successful receipt. The expected maximum acknowledgment time for a request to the subscribers' endpoint is 30 seconds. The service will attempt posting to the endpoint and then hold and retry until the subscriber endpoint responds with delivered or not accepted. The service will retry at least 3 days and skip to the next event after unsuccessful delivery. We suggest that the subscriber consider following:
- Endpoint response time requirements depend on the topic throughput. Please review the topic documentation for throughput.
- It is highly recommended to implement a queue behind the subscriber' endpoint in order to keep response time as low as possible.
- The subscriber must maintain a reasonable uptime to support the requirements of the integration scenario.
- Your HTTPS server endpoint must be accessible from the public web with a non-self-signed certificate. The certificate should be signed by a known Certificate Authority and should be reachable through DNS.
ESS Authentication
There are several ways that you can be sure that your endpoint being accessed by our service.
- We will always use the same client x509 certificate. The common name is
CN=webhook.api.concursolutions.com,O=Concur Technologies\, Inc.,L=Bellevue,ST=Washington,C=USand the certificate serial number is0AE315A13AB9EF8CADB9A46255C87283. - We will always use a digital signature, supplied in the request header
Concur-Signature. If you decide to use this authentication method you will need our Public Key.
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxS1LsXrEWEEMPooLHa4r
osCAnmkO3HaBAk0YcsDMR6hQeuQNLqRWP65TpbfTbKWmZ22Hzep3Ekhs1qvSZgI+
iq/bnVeDhkcD+LqVQGP+7fyE0E0bO96FOzMmtbRet4wAiiE9+uw5GmZfg+fRG3yI
y2N5u5p7VHJ1RwNugrIUQjhrLvZc+lhqR/aKTxQCQ5CGAgLZIcr3FIWCWrSBMK3d
Wy3KI+qe3ZX0STrCCNxl2UFnuuAa2RZZ2j4QtWHlNkyK+UEup+cGkvpc1XrT7anL
HlbTP6jE7MqB5sJ9r2EEzrJzJZjD13UqlzvI61tTC8SKpuk5AEaSsUV7RKlKUCjB
8wIDAQAB
-----END PUBLIC KEY-----
ESS Behavior
The Event Subscription service has the following characteristics from the subscriber perspective:
- Requests will come from
us.api.concursolutions.com,emea.api.concursolutions.com, orcn.api.concursolutions.com. - Connection will always be established using a client x509 certificate.
- Requests will always have a digital signature.
- Requests will be re-tried when the subscriber responds with HTTP Response Code(s): 5xx, 401, 403, or 429.
- Requests will not be re-tried when subscriber responds with HTTP Response Code(s):
- 2xx – Indicates successful receipt of the event.
- 4xx – Indicates posted event is unexpected or incorrectly formatted.
- Request will be retried until delivery OR event retention period expiration.
- Event retention period is 72 hours from the time of event being published.
- Events are not archived, but all of the event delivery attempts/responses are logged and retained for 30 days.
EXPENSE
Allocations
The SAP Concur Allocations API allows for the retrieval of allocation information as it relates to a Report ID, Entry ID, or Itemization ID. Using this API allows for an in-depth review of Expense Report Data and how that data has been allocated in SAP Concur. The Allocations API allows for the programmatic gathering of details on how the expense report data was allocated by the report owner, making it ideal for Data Gathering, Expense Reporting, and Validations.
Version
3.0
Retrieve All Allocations Per Entry or Report
GET /api/v3.0/expense/allocations
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
limit |
Int32 |
query |
The number of records to return. The default is 25 and the maximum is 100. |
offset |
string |
query |
The starting point of the next set of results, after the limit specified in the limit field has been reached. |
reportID |
string |
query |
The unique identifier for the report as it appears in the Concur Expense UI. Format: A variable-length string. Maximum length: 32 characters. |
entryID |
string |
query |
The unique identifier for the expense entry. |
itemizationID |
string |
query |
The unique identifier for the expense itemization. |
Note: userId is not a supported query string parameter for this API.
Request URL
https://www.concursolutions.com/api/v3.0/expense/allocations?limit=10
JSON Example of a Successful Response
{
"Items": [
{
"EntryID": "gWidFO7ikXSy7gHnNngC12jkL7khMiREv4g",
"Percentage": "100.00000000",
"IsPercentEdited": false,
"IsHidden": true,
"AccountCode1": "1",
"AccountCode2": null,
"Custom1": null,
"Custom2": null,
"Custom3": null,
"Custom4": null,
"Custom5": null,
"Custom6": null,
"Custom7": null,
"Custom8": null,
"Custom9": null,
"Custom10": null,
"Custom11": null,
"Custom12": null,
"Custom13": null,
"Custom14": null,
"Custom15": null,
"Custom16": null,
"Custom17": null,
"Custom18": null,
"Custom19": null,
"Custom20": null,
"ID": "gWmudeHM8AuFikny3Hrpz$s2gaNvc0E7Xfyw",
"URI": "https://www.concursolutions.com/api/v3.0/expense/allocations/gWmudeHM8AuFikny3Hrpz$s2gaNvc0E7Xfyw"
},
{
"EntryID": "gWidFO7ikXSy41$smPkwdC5cL1aku$pSgc$p4g",
"Percentage": "100.00000000",
"IsPercentEdited": false,
"IsHidden": true,
"AccountCode1": "1",
"AccountCode2": null,
"Custom1": null,
"Custom2": null,
"Custom3": null,
"Custom4": null,
"Custom5": null,
"Custom6": null,
"Custom7": null,
"Custom8": null,
"Custom9": null,
"Custom10": null,
"Custom11": null,
"Custom12": null,
"Custom13": null,
"Custom14": null,
"Custom15": null,
"Custom16": null,
"Custom17": null,
"Custom18": null,
"Custom19": null,
"Custom20": null,
"ID": "gWmudeHM8AuFhxez1E72ExJPksvTH0KPPyw",
"URI": "https://www.concursolutions.com/api/v3.0/expense/allocations/gWmudeHM8AuFhxez1E72ExJPksvTH0KPPyw"
}
]
}
Response
Retrieve a Single Allocation by ID
GET /api/v3.0/expense/allocations/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required The unique identifier for the allocation. |
user |
string |
query |
The login ID of the user who owns the allocation. The user must have the Web Services Admin role to use this parameter. |
Schema
Allocations
| Name | Type | Format | Description |
|---|---|---|---|
Items |
array |
Allocation |
The result collection. |
NextPage |
string |
- | The URI of the next page of results, if any. |
Allocation
| Name | Type | Format | Description |
|---|---|---|---|
AccountNumber |
string |
- | The primary accounting code assigned to the expense type associated with this allocation. Typically, expense types have only a primary account code. |
AccountCode2 |
string |
- | The secondary or alternative accounting code assigned to the expense type associated with this allocation. |
Custom1 through Custom20 |
CustomFieldExtension |
- | A custom field associated with the allocation. This field may or may not have data, depending on how Expense is configured. Format: Text field. Maximum length: 64 characters. |
EntryID |
string |
- | The unique identifier for the expense entry. |
ID |
string |
- | The unique identifier of the resource. |
IsHidden |
Boolean |
- | Indicates whether the allocation is hidden. Format: true or false |
IsPercentEdited |
Boolean |
- | Indicates whether the percentage has been edited. Format: true or false |
Percentage |
string |
- | The percentage of the expense that is included in this allocation. |
URI |
string |
- | The URI to the resource. |
Custom Field
| Name | Type | Format | Description |
|---|---|---|---|
Code |
string |
- | For list fields, this is the list item code. |
Label |
string |
- | The label value for the custom field. |
ListItemID |
string |
- | For list fields, this is the list item ID. |
Sequence |
integer |
- | The sequence value for this custom field i.e. the order in which this field appears on the form. |
Type |
string |
- | The custom field type. Possible values: Amount, Boolean, ConnectedList, Date, Integer, List, Number, Text |
Value |
string |
- | The value in the Org Unit or Custom field. For list fields, this is the name of the list item. Maximum length: 48 characters |
Request URL
https://www.concursolutions.com/api/v3.0/expense/allocations/gWmudeHM8AuFlD9Py%24p7cwkclNQvGC1JQPyw
JSON Example of a Successful Response
{
"EntryID": "gWidFO7ikXSy8HdaIfw32sJhcmk76TjD$p4g",
"Percentage": "100.00000000",
"IsPercentEdited": false,
"IsHidden": true,
"AccountCode1": "1",
"AccountCode2": null,
"Custom1": null,
"Custom2": null,
"Custom3": null,
"Custom4": null,
"Custom5": null,
"Custom6": null,
"Custom7": null,
"Custom8": null,
"Custom9": null,
"Custom10": null,
"Custom11": null,
"Custom12": null,
"Custom13": null,
"Custom14": null,
"Custom15": null,
"Custom16": null,
"Custom17": null,
"Custom18": null,
"Custom19": null,
"Custom20": null,
"ID": "gWmudeHM8AuFlD9Py$p7cwkclNQvGC1JQPyw",
"URI": "https://www.concursolutions.com/api/v3.0/expense/allocations/gWmudeHM8AuFlD9Py$p7cwkclNQvGC1JQPyw"
}
Attendee Types v3
The Attendee Type resource represents the type of attendee as configured in Concur.
- Retrieve all attendee types
- Retrieve attendee types by ID
- Create a new attendee type DEPRECATED: 05/19/2016 UNSUPPORTED: 11/19/2016
- Update existing attendee type
- Delete an attendee type DEPRECATED: 05/19/2016 UNSUPPORTED: 11/19/2016
- Schema
Version
3.0
Attendee Types v1 (Deprecated)
Retrieve all attendees types
GET /api/v3.0/expense/attendeetypes/
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
offset |
string |
query |
The starting point of the next set of results, after the limit specified in the limit field has been reached. |
limit |
Int32 |
query |
The number of records to return. Default value: 25 |
Request URL
https://www.concursolutions.com/api/v3.0/expense/attendeetypes?limit=10
JSON example of a successful response
{
"Items": [
{
"Name": "Business Guest",
"Code": "BUSGUEST",
"AttendeeFormID": "gWvidmKNPVEaOg$s66rqA62OJVXfvHBMs4sw",
"DuplicateSearchFields": [
"Title",
"Company",
"OwnerEmpName",
"FirstName",
"LastName"
],
"ConnectorID": "",
"AllowManuallyEnteredAttendees": true,
"AllowAttendeeCountEditing": true,
"ID": "gWjUHBxUY4iQLA9KTkbtUD6pc",
"URI": "https://www.concursolutions.com/api/v3.0/expense/attendeetypes/gWjUHBxUY4iQLA9KTkbtUD6pc"
},
{
"Name": "Healthcare Professional",
"Code": "HCP",
"AttendeeFormID": "gWvidmKNPVEH7wO$pDpD9$pk6xVlyJ4EjwIdA",
"DuplicateSearchFields": [
"Title",
"Custom18",
"ExternalId",
"FirstName",
"LastName",
"Custom7",
"Custom14",
"Custom15",
"Custom16",
"Custom17",
"Custom19",
"Custom8",
"Custom20"
],
"ConnectorID": "",
"AllowManuallyEnteredAttendees": true,
"AllowAttendeeCountEditing": false,
"ID": "gWjYOjoOorT3dhpHGto5H$poJuoa0m",
"URI": "https://www.concursolutions.com/api/v3.0/expense/attendeetypes/gWjYOjoOorT3dhpHGto5H$poJuoa0m"
}
]
}
Retrieve attendee types by ID
GET /api/v3.0/expense/attendeetypes/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required The ID of the attendee type. |
Request URL
https://www.concursolutions.com/api/v3.0/expense/attendeetypes/gWjYOjoOorT3dhpHGto5H%24poJuoa0m
JSON example of a successful response
{
"Name": "Healthcare Professional",
"Code": "HCP",
"AttendeeFormID": "gWvidmKNPVEH7wO$pDpD9$pk6xVlyJ4EjwIdA",
"DuplicateSearchFields": [
"Title",
"Custom18",
"ExternalId",
"FirstName",
"LastName",
"Custom7",
"Custom14",
"Custom15",
"Custom16",
"Custom17",
"Custom19",
"Custom8",
"Custom20"
],
"ConnectorID": "",
"AllowManuallyEnteredAttendees": true,
"AllowAttendeeCountEditing": false,
"ID": "gWjYOjoOorT3dhpHGto5H$poJuoa0m",
"URI": "https://www.concursolutions.com/api/v3.0/expense/attendeetypes/gWjYOjoOorT3dhpHGto5H$poJuoa0m"
}
Create a new attendee type
DEPRECATED: 05/19/2016 UNSUPPORTED: 11/19/2016
POST /api/v3.0/expense/attendeetypes
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
content |
- | body |
Required The AttendeeType object to create. |
Input
Response
Request URL
https://www.concursolutions.com/api/v3.0/expense/attendeetypes
JSON example of a successful response
{
"ID": "gWjYOj4JuT5VB$paQnF31149$sKgaM$p",
"URI": "https://www.concursolutions.com/api/v3.0/expense/attendeetypes/gWjYOj4JuT5VB$paQnF31149$sKgaM$p"
}
Update existing attendee type
PUT /api/v3.0/expense/attendeetypes/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required The ID of the attendee type. |
content |
- | body |
Required The partial or complete Attendee object to update. |
Input
Response
Request URL
https://www.concursolutions.com/api/v3.0/expense/attendeetypes/gWjYOjoa7Fe0HsTGEk417OCzqUf1A
Delete an attendee type
DEPRECATED: 05/19/2016 UNSUPPORTED: 11/19/2016
DELETE /api/v3.0/expense/attendeetypes{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required The ID of the attendee type to delete |
Input
Response
Request URL
https://www.concursolutions.com/api/v3.0/expense/attendeetypes/gWjYOjomP3Jxp6dFC%24pIg%24sc99nQQ3q
Schema
Attendee Type
| Name | Type | Format | Description |
|---|---|---|---|
AllowAttendeeCountEditing |
boolean |
- | Determines whether users are allowed to edit the count for this attendee type. Format: true or false |
AllowManuallyEnteredAttendees |
boolean |
- | Determines whether users are allowed to add attendees for this attendee type. Format: true or false |
AttendeeFormID |
string |
- | The unique identifier for the attendee form for this attendee type. |
Code |
string |
- | A code that indicates the type of attendee. Examples: EMPLOYEE, SPOUSE, BUSGUEST. Maximum length: 40 characters |
ConnectorID |
string |
- | The unique identifier for the Application Connector that is the data source for this attendee type. When this field is empty, the Expense database is the data source. |
DuplicateSearchFields |
Array |
AttendeeType | The list of Attendee field IDs used by the Add Attendee user interface to alert users that the attendee they want to add is a possible duplicate. This parent element has a DuplicateSearchField child element for each field ID. |
ID |
string |
- | The unique identifier of the resource. |
Name |
string |
- | The name for the attendee type. This name must be unique. Maximum length: 40 characters |
URI |
string |
- | The URI to the resource. |
Attendees v3
- Retrieve all attendees owned by the specified user
- Retrieve a single attendee by ID
- Create a new attendee
- Update existing attendees
- Schema
Related
Retrieve all attendees owned by the specified user
Request
URI
Template
GET /api/v3.0/expense/attendees
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
externalID |
string |
query |
The external ID of an attendee. By entering a value for this parameter, you can limit the results to the attendees who match the specified external ID. Up to 10 comma-separated external IDs may be specified. |
attendeeTypeID |
string |
query |
The ID of an attendee type. By entering a value for this parameter, you can limit the results to the attendees who match the specified type. |
offset |
string |
query |
The starting point of the next set of results, after the limit specified in the limit field has been reached. |
limit |
Int32 |
query |
The number of records to return. Default value: 25 |
user |
string |
query |
The login ID of the user that has added the attendee to an expense. The user who is performing this API request must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter |
Payload
None
Response
Payload
Example
Request
GET https://www.concursolutions.com/api/v3.0/expense/attendees?limit=15
Response
{
"Items": [
{
"AttendeeTypeCode": "NOSHOWS",
"AttendeeTypeID": "gWjYOjoCmOo2Ua$pH4qnCsQxgS8Z0E",
"FirstName": null,
"LastName": "No Show Attendee",
"MiddleInitial": null,
"Suffix": null,
"Company": null,
"Title": null,
"ExternalID": null,
"HasExceptionsPrevYear": false,
"HasExceptionsYTD": false,
"TotalAmountPrevYear": 0,
"TotalAmountYTD": 0,
"VersionNumber": 1,
"OwnerName": "System, Concur",
"OwnerLoginID": "ConcurSystem",
"CurrencyCode": "USD",
"Custom1": null,
"Custom2": null,
"Custom3": null,
"Custom4": null,
"Custom5": null,
"Custom6": null,
"Custom7": null,
"Custom8": null,
"Custom9": null,
"Custom10": null,
"Custom11": null,
"Custom12": null,
"Custom13": null,
"Custom14": null,
"Custom15": null,
"Custom16": null,
"Custom17": null,
"Custom18": null,
"Custom19": null,
"Custom20": null,
"Custom21": null,
"Custom22": null,
"Custom23": null,
"Custom24": null,
"Custom25": null,
"ID": "gWj3IHRYiHZGUtIO83ILhbNHqCsjMmkvj$pQ",
"URI": "https://www.concursolutions.com/api/v3.0/expense/attendees/gWj3IHRYiHZGUtIO83ILhbNHqCsjMmkvj$pQ"
}
]
}
Retrieve a single attendee by ID
Request
URI
Template
/api/v3.0/expense/attendees/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required The attendee object to create. |
user |
string |
query |
The login ID of the user that has added the attendee to an expense. The user who is performing this API request must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter |
Payload
None
Response
Payload
Example
Request
GET https://www.concursolutions.com/api/v3.0/expense/attendees/gWj3IHRYiHZGd0HJy%24p5Uk0zITlsMX0ymT%24pA
Response
{
"AttendeeTypeCode": "PRIVATE",
"AttendeeTypeID": "gWjYOjoa7Fe0HsTGEk417OCzqUf1A",
"FirstName": "Diego",
"LastName": "Rodriguez",
"MiddleInitial": null,
"Suffix": null,
"Company": "Contoso",
"Title": null,
"ExternalID": "1",
"HasExceptionsPrevYear": false,
"HasExceptionsYTD": false,
"TotalAmountPrevYear": 0,
"TotalAmountYTD": 0,
"VersionNumber": 1,
"OwnerName": "System, Concur",
"OwnerLoginID": "ConcurSystem",
"CurrencyCode": "USD",
"Custom1": null,
"Custom2": null,
"Custom3": null,
"Custom4": null,
"Custom5": null,
"Custom6": null,
"Custom7": null,
"Custom8": null,
"Custom9": null,
"Custom10": null,
"Custom11": null,
"Custom12": null,
"Custom13": null,
"Custom14": null,
"Custom15": null,
"Custom16": null,
"Custom17": null,
"Custom18": null,
"Custom19": null,
"Custom20": null,
"Custom21": null,
"Custom22": null,
"Custom23": null,
"Custom24": null,
"Custom25": null,
"ID": "gWj3IHRYiHZGd0HJy$p5Uk0zITlsMX0ymT$pA",
"URI": "https://www.concursolutions.com/api/v3.0/expense/attendees/gWj3IHRYiHZGd0HJy$p5Uk0zITlsMX0ymT$pA"
}
Create a new attendee
Request
URI
Template
/api/v3.0/expense/attendees
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
user |
string |
query |
The login ID of the user that has added the attendee to an expense. The user who is performing this API request must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter |
Payload
Response
Payload
Example
Request
POST https://www.concursolutions.com/api/v3.0/expense/attendees
Response
{
"ID": "gWj3IHRYiHZOQ2T9NNdJ$plN$s7$sG8LhZwjoQ",
"URI": "https://www.concursolutions.com/api/v3.0/expense/attendees/gWj3IHRYiHZOQ2T9NNdJ$plN$s7$sG8LhZwjoQ"
}
Update existing attendees
Request
URI
Template
/api/v3.0/expense/attendees/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required The attendee ID |
user |
string |
query |
The login ID of the user that has added the attendee to an expense. The user who is performing this API request must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter |
Payload
Response
Payload
Example
Request
- Showing developers exactly what they can expect in request and response values when using is perhaps the simplest way to complete this portion of the documentation.
- Use triple backticks to create fenced code blocks and a language identifier for syntax highlighting.
- See Creating and highlighting code blocks
PUT https://www.concursolutions.com/api/v3.0/expense/attendees/gWj3IHRYiHZOQ2T9NNdJ%24plN%24s7%24sG8LhZwjoQ
Response
ToDo
Schema
Attendees
| Name | Type | Format | Description |
|---|---|---|---|
Items |
array |
Attendee |
The result collection. |
NextPage |
string |
- | The URI of the next page of results, if any. |
Attendee
| Name | Type | Format | Description |
|---|---|---|---|
AttendeeTypeCode |
string |
- | A code that indicates the type of attendee. Examples: EMPLOYEE, SPOUSE, BUSGUEST. Maximum length: 40 characters |
AttendeeTypeID |
string |
- | The ID of the attendee type. To obtain the attendee type ID value, use the GET /expense/attendeetypes endpoint. The value of the ID element in the response is the attendee type ID. |
Company |
string |
- | The name of the attendee's company. Maximum length: 150 characters |
CurrencyCode |
string |
- | The 3-letter ISO 4217 currency code for monetary amounts related to an attendee. |
Custom1 through Custom25 |
CustomField |
- | A custom field associated with the attendee. This field may or may not have data, depending on how Expense is configured. |
ExternalID |
string |
- | A unique identifier for the attendee, assigned outside of Concur. Maximum length: 48 characters NOTE: For HCP connectors where information returned to Concur represents one record per attendee+address pair, this value should be a unique identifier for that pair, and the unique identifier for the individual should be placed into a custom field. |
FirstName |
string |
- | The attendee's first name. Maximum length: 50 characters |
HasExceptionsPrevYear |
Boolean |
- | Determines whether the attendee had exceptions in the previous year, based on yearly total limits for attendees. Format: true or false |
HasExceptionsYTD |
Boolean |
- | Determines whether the attendee has exceptions in the current year, based on yearly total limits for attendees. Format: true or false |
ID |
string |
- | The unique identifier of the resource. |
LastName |
string |
- | The attendee's last name. Maximum length: 132 characters |
MiddleInitial |
string |
- | The attendee's middle initial. Maximum length: 1 character |
OwnerLoginID |
string |
- | The login ID of the user who owns the attendee record. |
OwnerName |
string |
- | The name of the user who owns the attendee record. |
Suffix |
string |
- | The attendee's name suffix. Maximum length: 32 characters |
Title |
string |
- | The attendee's title. Maximum length: 32 characters |
TotalAmountPrevYear |
Decimal |
- | The total amount spent on the attendee in the previous calendar year. |
TotalAmountYTD |
Decimal |
- | The total amount spent on the attendee in the current calendar year. |
URI |
string |
- | The URI to the resource. |
VersionNumber |
Int32 |
- | The attendee's version number. |
Custom Field
| Name | Type | Format | Description |
|---|---|---|---|
Code |
string |
- | For list fields, this is the list item code. |
ListItemID |
string |
- | For list fields, this is the list item ID. |
Type |
string |
- | The custom field type. Possible values: Amount, Boolean, ConnectedList, Date, Integer, List, Number, Text |
Value |
string |
- | The value in the Org Unit or Custom field. For list fields, this is the name of the list item. Maximum length: 48 characters |
Digital Tax Invoices
The Digital Tax Invoice web service allows digital tax invoice validators to view tax invoices and update them with a validation status. This web service currently supports the Comprobante Fiscal Digital (CFD) digital tax invoice format used in Mexico. Other countries may be supported in future releases.
- Retrieve All Digital Tax Invoices That Can Be Validated by the User Based On the Search Criteria
- Retrieve a Single Digital Tax Invoice by ID
- Update a Specified Digital Tax Invoice
- Schema
Version
3.0
Retrieve All Digital Tax Invoices That Can Be Validated by the User Based On the Search Criteria
GET /api/v3.0/expense/digitaltaxinvoices
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
offset |
query |
string |
The starting point of the next set of results, after the limit specified in the limit field has been reached. |
limit |
query |
Int32 |
The number of records to return. Default value: 25 |
modifiedafter |
query |
string |
A modification date for the queue record; this parameter can be used to limit the results of the GET request to the queue items that have been added since the last time the validation company queried the queue. The user must have the Web Services Admin role to use this parameter. |
Request URL
https://www.concursolutions.com/api/v3.0/expense/digitaltaxinvoices?limit=5
Retrieve a Single Digital Tax Invoice by ID
GET /api/v3.0/expense/digitaltaxinvoices/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
path |
string |
Required The ID of the digital tax invoice. |
Request URL
https://www.concursolutions.com/api/v3.0/expense/digitaltaxinvoices/gWj3IHRYiHZGRTDN6y4r4LN3phszY33HT%24pQ
Update a Specified Digital Tax Invoice
PUT /api/v3.0/expense/digitaltaxinvoices/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
content |
body |
- | Required A status update for the digital tax invoice. |
id |
path |
string |
Required The ID of the digital tax invoice to update. |
Schema
Digital Tax Invoices
| Name | Type | Format | Description |
|---|---|---|---|
Items |
array |
Digital Tax Invoice | The result collection. |
NextPage |
string |
- | The URI of the next page of results, if any. |
Digital Tax Invoice
| Name | Type | Format | Description |
|---|---|---|---|
ConcurReceiptID |
string |
- | Required The ID of the digital tax invoice in plain text. |
ID |
string |
- | The unique identifier of the resource. |
URI |
string |
- | The URI to the resource. |
AccountID |
string |
- | Required The unique identifier assigned by the validation partner to the SAP Concur client company that owns the digital tax invoices. |
DocumentID |
string |
- | Required The ID of the report in plain text. |
ReceiptData |
string |
- | Required The digital tax invoice data. |
Request URL
https://www.concursolutions.com/api/v3.0/expense/digitaltaxinvoices/gWj3IHRYiHZGUtIO83ILhbNHqCsjMmkvj%24pQ
Currency Admin Configuration
Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.
Currency Admin Configuration
In order for users to submit expense reports based on uploaded exchange rates, the expense administrator may consider additional configurations.
As the administrator, navigate to the Currency Admin page:
Administration >> Expense >> Expense Admin >> Currency Admin >> Settings
- Ensure Currently Loaded Exchange Rates is checked to consume exchange rates.
- The Exchange Rate Source provides three options in which what rates are retrieved:
- Search Local then External Sources: Custom rates are loaded first and, if not found, consume rates from an external source.
- Use Local Exchange Rates Only: Custom rates only.
- Use External Exchange Rates Only: Our default external exchange rate source is OANDA Live Exchange Rates.
- Exchange rate Markup (percentage): Increase all rates returned by an additional percentage.
- Allow Inversion of currency rate pairs: As currency rates are bidirectional, this allows retrieval of a rate in the opposite direction of an uploaded exchange rate, calculated as an inverse of the original rate.
Exchange Rate v4
The Exchange Rate Broker API provides allows users to create custom exchange rates for a company. For additional configuration information, please see the Currency Admin Configuration page.
Limitations: The API currently allows a maximum of 100 exchange rates per POST request. This API is only available to users who have been granted access by SAP Concur. Access to this documentation does not provide access to the API.
- Products and Editions
- Scope Usage
- Dependencies
- Access Token Usage
- Create Custom Exchange Rates
- Schema
Process Flow

Products and Editions
- Concur Expense Professional Edition
- Concur Expense Standard Edition
- Concur Travel Professional Edition
- Concur Travel Standard Edition
- Concur Invoice Professional Edition
- Concur Invoice Standard Edition
- Concur Request Professional Edition
- Concur Request Standard Edition
Scope Usage
| Name | Description | Endpoint |
|---|---|---|
expense.exchangerate.writeonly |
Create custom exchange rates. | POST |
Dependencies
None.
Access Token Usage
This API supports company level access tokens.
Create Custom Exchange Rates
Create a set of custom exchange rates for the given of dates and currency pairs.
Scopes
expense.exchangerate.writeonly - Refer to Scope Usage for full details.
Request
URI
Template
POST {datacenter}/exchangerate/v4/rates
Parameters
None.
Headers
Content-Type: application/jsonAuthorization: Bearer Token
Payload
Example JSON request body:
{
"currency_sets": [
{
"from_crn_code": "USD",
"start_date": "2019-01-01",
"rate": 1.2,
"to_crn_code": "EUR"
}, {
"from_crn_code": "USD",
"start_date": "2019-01-01",
"rate": 1.3,
"to_crn_code": "CAD"
}
]
}
Response
In case of success, the JSON response body will be the same array of exchange rate items with overallStatus, and individual rate upload statusCode and statusMessage. A bulk upload can be partially successful.
Status Codes
- 200 OK
- 400 Bad Request
- 401 Unauthorized
- 403 Forbidden
- 406 Not Acceptable
- 413 Payload Too Large
- 500 Internal Server Error
- 503 Service Unavailable
- 504 Gateway Timeout
Headers
concur-correlationidis an SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace.- RFC 7231 Content-Type
- RFC 7230 Content-Length
Payload
Successfully Created Response:
{
"overallStatus": "Success",
"message": "Requests completed successfully",
"currencySets": [
{
"from_crn_code": "USD",
"start_date": "2019-01-01",
"rate": 1.2,
"to_crn_code": "EUR",
"statusMessage": "success",
"statusCode": 200
},
{
"from_crn_code": "USD",
"start_date": "2019-01-01",
"rate": 1.3,
"to_crn_code": "CAD",
"statusMessage": "success",
"statusCode": 200
}
]
}
Example - Success
Request
POST https://us.api.concursolutions.com/exchangerate/v4/rates
Accept: application/json
Authorization: Bearer {TOKEN}
Content-Type: application/json
{
"currency_sets": [
{
"from_crn_code": "USD",
"start_date": "2019-01-01",
"rate": 1.2,
"to_crn_code": "EUR"
}
, {
"from_crn_code": "USD",
"start_date": "2019-01-01",
"rate": 1.3,
"to_crn_code": "CAD"
}
]
}
Response
HTTP/1.1 200 OK
Content-Type: application/json
Date: Thu, 01 Jan 2020 18:50:00 GMT
concur-correlationid: abcd1234-wxyz-6789-abcd-abc123456789
{
"overallStatus": "Success",
"message": "Requests completed successfully",
"currencySets": [
{
"from_crn_code": "USD",
"start_date": "2019-01-01",
"rate": 1.2,
"to_crn_code": "EUR",
"statusMessage": "success",
"statusCode": 200
},
{
"from_crn_code": "USD",
"start_date": "2019-01-01",
"rate": 1.3,
"to_crn_code": "CAD",
"statusMessage": "success",
"statusCode": 200
}
]
}
Example - Partial Success
This example only partially succeeds to create all exchange rates due to an invalid from_crn_code in the first array entry. However, the second array entry is successfully created.
Request
POST https://us.api.concursolutions.com/exchangerate/v4/rates
Accept: application/json
Authorization: Bearer {TOKEN}
Content-Type: application/json
{
"currency_sets": [
{
"from_crn_code": "INVALID",
"start_date": "2019-01-01",
"rate": 1.2,
"to_crn_code": "EUR"
}, {
"from_crn_code": "USD",
"start_date": "2019-01-01",
"rate": 1.3,
"to_crn_code": "CAD"
}
]
}
Response
HTTP/1.1 200 OK
Content-Type: application/json
Date: Thu, 01 Jan 2020 18:50:00 GMT
concur-correlationid: abcd1234-wxyz-6789-abcd-abc123456789
{
"overallStatus": "Partial Success",
"message": "Requests completed with errors",
"currencySets": [
{
"from_crn_code": "INVALID",
"start_date": "2019-01-01",
"rate": 1.2,
"to_crn_code": "EUR",
"statusMessage": "Invalid request received",
"statusCode": 400
},
{
"from_crn_code": "USD",
"start_date": "2019-01-01",
"rate": 1.3,
"to_crn_code": "CAD",
"statusMessage": "success",
"statusCode": 200
}
]
}
Schema
BulkExchangeRateUploadRequest
| Name | Type | Format | Description |
|---|---|---|---|
currency_sets |
array |
ExchangeRateUploadRequest |
Required An array of exchange rate upload requests. |
ExchangeRateUploadRequest
| Name | Type | Format | Description |
|---|---|---|---|
from_crn_code |
string |
- | Required ISO 4217 Alphabetic code of the currency converting from. |
to_crn_code |
string |
- | Required ISO 4217 Alphabetic code of the currency converting to. |
start_date |
string |
YYYY-MM-DD |
Required UTC time for exchange rate come to be effective. |
rate |
number |
- | Required Custom exchange rate. |
BulkExchangeRateUploadResponse
| Name | Type | Format | Description |
|---|---|---|---|
overallStatus |
string |
- | Overall status for this bulk upload. |
message |
string |
- | Overall message for this bulk upload. |
currencySets |
array |
ExchangeRateUploadResponse |
Array of individual upload results. |
ExchangeRateUploadResponse
| Name | Type | Format | Description |
|---|---|---|---|
from_crn_code |
string |
- | ISO 4217 alphabetic code of the currency converting from. |
to_crn_code |
string |
- | ISO 4217 alphabetic code of the currency converting to. |
start_date |
string |
YYYY-MM-DD |
UTC time for exchange rate come to be effective. |
rate |
number |
- | Custom exchange rate. |
statusCode |
number |
- | HTTP status code for uploading this custom currency set. |
statusMessage |
string |
- | HTTP message for uploading this custom currency set. |
Error
| Name | Type | Format | Description |
|---|---|---|---|
errorId |
string |
- | The unique identifier of the error associated with the response or is it error response itself. |
errorMessage |
string |
- | The detailed error message. |
httpStatus |
string |
- | The HTTP response code and phrase for the response. |
path |
string |
- | The URI of the attempted request. |
timestamp |
string($date-time) |
- | The datetime when the error was captured. Example: 2016-10-04T00:53:25.931+0000 |
validationErrors |
array |
ValidationError |
Validation errors for this request. |
ValidationError
| Name | Type | Format | Description |
|---|---|---|---|
message |
string |
- | The detailed message of the validation error. |
source |
string |
- | The type of validation which failed. |
Company Card Transactions
The corporate or credit card charges that are available for use in expense reports for the OAuth consumer.
Retrieves a list of unassigned company card charges for the user specified in the OAuth access token.
Version
1.1
URI
https://www.concursolutions.com/api/expense/expensereport/v1.1/CardCharges
Operations
Request
Request Parameters
None.
Content Types
application/xml
Authorization Header
Authorization header with OAuth token for valid SAP Concur user. Required.
Response
Content Types
application/xml
Schema
This request will return a CardCharges parent element with a CardCharge child element for each transaction.
CardCharge Child Elements
| Element | Description |
|---|---|
| CardNumber | The number of the card, with all digits obscured OTHER than last 4 digits. |
| ExpKey | The code for the expense type of the transaction |
| Merchant | The merchant name for the transaction. |
| ExpName | The name of the expense type of the transaction. |
| TransactionAmount | The amount of the card transaction. |
| TransactionCrnCode | The currency code of the transaction amount. |
| TransactionDate | The date of the transaction. |
Examples
XML Example Request
GET https://www.concursolutions.com/api/expense/expensereport/v1.1/CardCharges/ HTTP/1.1
Authorization: OAuth {access token}
...
XML Example of Successful Response
HTTP/1.1 200 OK
Content-Type: application/xml
<CardCharges
xmlns="https://www.concursolutions.com/api/expense/expensereport/2011/03">
<CardCharge>
<CardNumber>XXXXXXXXX1111</CardNumber>
<ExpKey>CARRT</ExpKey>
<ExpName>Car Rental</ExpName>
<Merchant>Hertz</Merchant>
<TransactionAmount>283.88000000</TransactionAmount>
<TransactionCrnCode>USD</TransactionCrnCode>
<TransactionDate>2010-08-19T00:00:00</TransactionDate>
</CardCharge>
<CardCharge>
<CardNumber>XXXXXXXXX1111</CardNumber>
<ExpKey>UNDEF</ExpKey>
<ExpName>Undefined</ExpName>
<Merchant>King Tires</Merchant>
<TransactionAmount>274.13000000</TransactionAmount>
<TransactionCrnCode>USD</TransactionCrnCode>
<TransactionDate>2010-08-19T00:00:00</TransactionDate>
</CardCharge>
</CardCharges>
Expense Delegators
Users that have granted delegate permissions to the another Expense user.
Retrieves the list of users that have granted delegate permissions to the user specified in the OAuth access token.
Version
1.1
URI
https://www.concursolutions.com/api/expense/expensereport/v1.1/Delegators
Operations
Request
Request Parameters
None.
Headers
Authorization Header
Authorization header with OAuth token for valid SAP Concur user. Required.
Accept Header
application/xml
Response
Content Types
application/xml
Schema
This request will return a DelegatorsList parent element with a Delegator parent element for each user that has granted delegate rights to the OAuth consumer.
Delegator Elements
| Element | Description |
|---|---|
| CanApprove | Whether the delegate is granted the right to approve expense reports on behalf of the delegator. |
| CanPrepare | Whether the delegate is granted the right to create expense reports on behalf of the delegator. |
| CanSubmit | Whether the delegate is granted the right to submit expense reports on behalf of the delegator. |
| CanTemporaryApprove | Whether the delegate is granted the same temporary approval rights as the delegator. |
| CanViewReceipts | Whether the delegate is granted the right to view receipts on behalf of the delegator. |
| ReceiveApprovalEmails | Whether the delegate also receives the approval emails sent to the delegator. |
| ReceivesEmails | Whether the delegate also receives the SAP Concur emails sent to the delegator. |
| DelegatorXUserID | The user ID of the delegator. |
Examples
XML Example Request
GET https://www.concursolutions.com/api/expense/expensereport/v1.1/Delegators HTTP/1.1
Authorization: OAuth {access token}
...
XML Example of Successful Response
HTTP/1.1 200 OK
Content-Type: application/xml
<DelegatorsList xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Delegator>
<CanApprove>N</CanApprove>
<CanPrepare>Y</CanPrepare>
<CanSubmit>Y</CanSubmit>
<CanTemporaryApprove>N</CanTemporaryApprove>
<CanViewReceipts>Y</CanViewReceipts>
<ReceiveApprovalEmails>N</ReceiveApprovalEmails>
<ReceivesEmails>N</ReceivesEmails>
<DelegatorXUserID>terryb@example.com</DelegatorXUserID>
</Delegator>
<Delegator>
<CanApprove>N</CanApprove>
<CanPrepare>Y</CanPrepare>
<CanSubmit>Y</CanSubmit>
<CanTemporaryApprove>N</CanTemporaryApprove>
<CanViewReceipts>N</CanViewReceipts>
<ReceiveApprovalEmails>N</ReceiveApprovalEmails>
<ReceivesEmails>N</ReceivesEmails>
<DelegatorXUserID>patd@example.com</DelegatorXUserID>
</Delegator>
</DelegatorsList>
Entries
- Retrieve All Expense Entries
- Create a New Expense Entry
- Update an Expense Entry
- Delete an Expense Entry
- Schema
The Expense Entries API is used to manage expense reports and their entries in SAP Concur solutions. It allows for the synchronizing and reconciliation of expense related information with your internal systems and reporting modules.
1.1 documentation is available here.
Retrieve All Expense Entries
Version 2.0, covers a wider range of partner scenarios and is recommended as the first step. However, depending on the entries you need to retrieve, using a combination of version 2.0 and version 3.0 should be considered. To see examples, review the VAT Reclaim integration guide.
Create a New Expense Entry
POST /api/v3.0/expense/entries
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
content |
body |
- | Required The expense entry object to create. |
user |
string |
query |
The login ID of the user who owns the entries. |
Request URL
https://www.concursolutions.com/api/v3.0/expense/entries
JSON Example of a Successful Response
{
"ID": "gWidFO7ikXV647DRpQmvCXeFNA4VPTOczCg",
"URI": "https://www.concursolutions.com/api/v3.0/expense/entries/gWidFO7ikXV647DRpQmvCXeFNA4VPTOczCg"
}
Updates an Expense Entry
PUT /api/v3.0/expense/entries/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required The expense entry ID. |
content |
body |
- | Required The partial or complete expense entry object to update. |
Request URL
https://www.concursolutions.com/api/v3.0/expense/entries/gWidFO7ikXV66iSvqtG6Yd0wZ%24s4ftzvzTCg
Delete an Expense Entry
DELETE /api/v3.0/expense/entries/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required The ID of the expense entry to delete. |
user |
string |
query |
The login ID of the user who owns the entries. |
Request URL
https://www.concursolutions.com/api/v3.0/expense/entries/gWidFO7ikXV66iSvqtG6Yd0wZ%24s4ftzvzTCg
Schema
Entries
| Name | Type | Format | Description |
|---|---|---|---|
Items |
array |
Entry | The result collection. |
NextPage |
string |
- | The URI of the next page of results, if any. |
Entry
| Name | Type | Format | Description |
|---|---|---|---|
AllocationType |
string |
- | The type of allocations for the expense. Supported values: P - partial allocation, F - full allocation, N - no allocation. Use the GET /expense/allocations function to get information about this entry's allocations. |
ApprovedAmount |
decimal |
- | The approved amount of the expense entry, in the report currency. |
CompanyCardTransactionID |
string |
- | The unique identifier for a company card transaction that is associated with this expense. Concur Expense uses the Credit Card Import job to import company card transactions. Use the GET CompanyCardTransactions function to get information about these card transactions. This element is null when there is no company card transaction associated with this expense. |
Custom1 through Custom40 |
customField |
- | The details from the Custom fields. These fields may not have data, depending on the configuration. |
Comment |
string |
- | A comment that describes the expense entry. Maximum length: 500 characters |
Description |
string |
- | The description of the expense. Maximum length: 64 characters |
ElectronicReceiptID |
string |
- | The unique identifier for an eReceipt that is associated with this expense. Use the GET eReceipts function to get information about this eReceipt. This element is null when there is no eReceipt associated with this expense. |
EmployeeBankAccountID |
string |
- | The unique identifier of an employee bank account that is associated with this expense. Typically, this element is used when Expense Pay reimburses the employee for this expense. Use the GET BankAccounts function to get information about this bank account. |
ExchangeRate |
decimal |
- | The currency conversion rate that converts the transaction amount that is in the transaction currency into the posted amount that is in the report currency. This element is typically not provided. If this element is empty for transactions in a currency different than the user's reimbursement currency, Expense will use the company's configured exchange rates to determine the posted amount for the transaction. If the system is not able to determine the exchange rate, a value of 1.0 will be used. |
ExpenseTypeCode |
string |
- | Required The code for the expense type. Use GET /expense/expensegroupconfigurations to learn the expense type code for expense types that are active for this report's policy. |
ExpenseTypeName |
string |
- | The name of the expense type, localized to the user's language. |
FormID |
string |
- | The ID of the form used by this expense entry. |
HasAppliedCashAdvance |
boolean |
true / false |
Whether the entry has a cash advance applied to it. |
HasAttendees |
boolean |
true / false |
Indicates whether the expense has attendees. Use the GET /expense/entryattendeeassociations function to get information about this entry's attendees. |
HasComments |
boolean |
true / false |
Whether or not the expense entry has comments. |
HasExceptions |
boolean |
true / false |
Whether the expense has exceptions. Use the GET ExpenseEntryExceptions function to get information about this entry's exceptions. |
HasImage |
boolean |
true / false |
Indicates whether there is an entry image attached to the entry. Use the GET Entry Images function to get this entry image. |
HasItemizations |
boolean |
true / false |
Indicates whether the expense has itemizations. Use the GET /expense/itemizations function to get information about this entry's itemizations. |
HasVAT |
boolean |
true / false |
Indicates whether the entry has VAT data. |
ID |
string |
- | The unique identifier of the resource. |
IsBillable |
boolean |
true / false |
Indicates whether the expense is billable. |
IsImageRequired |
boolean |
true / false |
Indicates whether an entry image is required for the entry. |
IsPaidByExpensePay |
boolean |
true / false |
Whether the entry is paid using the Expense Pay service. This element has a value if the report has reached the Processing Payment workflow step, because this is when Concur Expense determines whether it will be paid by Expense Pay. |
IsPersonal |
boolean |
true / false |
Indicates whether the expense is personal (that is, non-reimbursable). |
IsPersonalCardCharge |
boolean |
true / false |
Indicates whether the expense entry was imported from a personal card feed. Concur Expense uses the Yodlee API to import these card transactions. |
Journey |
journey |
- | Journey data. This element is used when the entry is a mileage expense. For expense types with an expense code that is either Company Car or Personal Car, the Journey child element is required. This element should not be used for expense types with an expense code that is neither Company Car nor Personal Car. |
LastModified |
dateTime |
- | The UTC date when the entry was last modified. |
LocationCountry |
string |
- | The 2-letter ISO 3166-1 country code where the expense was incurred. |
LocationID |
string |
- | The unique identifier for the location where the expense was incurred. Use the GET /common/locations function to get information for this location. |
LocationName |
string |
- | The location where the expense was incurred, usually the city name. |
LocationSubdivision |
string |
- | The ISO 3166-2:2007 country subdivision state, province, or other country subdivision where the expense was incurred. |
OrgUnit1 through OrgUnit6 |
customField |
- | The details from the Org Unit fields. These fields may not have data, depending on the configuration. |
PaymentTypeID |
string |
- | Required The ID of the payment type for the entry. Use GET /expense/expensegroupconfigurations to learn the payment type ID for payment types that are active for this report's expense group. For mileage expenses, use the Cash payment type. For expense types with an expense code that uses a transaction amount instead of a distance, this element is required. This element should not be used for expense types with an expense code for Company Car or Personal Car, because these two expense codes always use the Cash payment type. |
PaymentTypeName |
string |
- | The name of the payment type, localized to the user's language. |
PostedAmount |
decimal |
- | The amount of the expense entry, in the report currency. |
ReceiptReceived |
boolean |
true / false |
Indicates whether this entry has been reviewed by a processor. Format: true or false |
ReportID |
string |
- | Required The report ID of the report where the entry will be added. |
ReportOwnerID |
string |
- | The login ID of the report owner. Use the GET User Information function to learn details about this user. |
SpendCategoryCode |
string |
- | The ID of the spending category that is specified for this expense entry. |
SpendCategoryName |
string |
- | The name of the spending category that is specified for this expense entry, localized to the user's language. |
TaxReceiptType |
string |
- | The receipt type for this entry. Supported values: T - tax receipt, R - regular receipt, N - no receipt |
TransactionAmount |
decimal |
- | Required The amount of the expense entry, in the transaction currency paid to the vendor. |
TransactionCurrencyCode |
string |
- | Required The 3-letter ISO 4217 currency code for the expense entry transaction amount. This is the currency in which the vendor was paid. For expense types with an expense code that uses a transaction amount instead of a distance, this element is required. This element should not be used for expense types with an expense code for Company Car or Personal Car, because for these two expense codes the currency is always the Report Currency. |
TransactionDate |
dateTime |
YYYY-MM-DD |
Required The date when the good or service associated with this expense entry was provided. |
TripID |
string |
- | The unique identifier of a trip in the Itinerary Service that includes a travel booking associated with this expense. Use GET ItineraryDetails to get information about this trip and the travel booking. This element is null when there is no trip associated with the expense. |
URI |
string |
- | The URI to the resource. |
VendorDescription |
string |
- | The name of the vendor for the expense entry. Maximum length: 64 characters |
VendorListItemID |
string |
- | The unique identifier for a vendor list item. Use the GET /common/lists function to get information about this list item. |
VendorListItemName |
string |
- | The name of an item from a vendor list. |
CustomField
| Name | Type | Format | Description |
|---|---|---|---|
Code |
string |
- | For list fields, this is the list item code. |
ListItemID |
string |
- | For list fields, this is the list item ID. |
Type |
string |
- | The custom field type. Supported values: Amount, Boolean, ConnectedList, Date, Integer, List, Number, Text |
Value |
string |
- | The value in the Org Unit or Custom field. For list fields, this is the name of the list item. Maximum length: 48 characters |
Journey
| Name | Type | Format | Description |
|---|---|---|---|
BusinessDistance |
Int32 |
- | The portion of the journey for business use, in the report owner's unit of measure for distances. This element is required in order to post a personal car mileage expense entry, or to post a company car mileage expense when there is no PersonalDistance value. When using the Odometer elements, the sum of PersonalDistance and BusinessDistance must equal the difference between OdometerEnd and OdometerStart. |
EndLocation |
string |
- | Required Indicates where the journey ended. This is also known as the "To Location". Maximum length: 100 characters |
NumberOfPassengers |
Int32 |
- | The number of people in the vehicle during the journey. Used with Variable-Rate, Personal or Company Car. |
OdometerEnd |
Int32 |
- | The odometer reading at the end of the journey. The value must be greater than the OdometerStart value. This element is used with Variable-Rate and Company Car configuration types. |
OdometerStart |
Int32 |
- | The odometer reading at the start of the journey. This element is used with Variable-Rate and Company Car configuration types. |
PersonalDistance |
Int32 |
- | The portion of the journey for personal use. This element is required in order to post a company car mileage expense when there is no BusinessDistance value. When using the Odometer elements, the sum of PersonalDistance and BusinessDistance must equal the difference between OdometerEnd and OdometerStart. Used with Company Car configuration types. |
StartLocation |
string |
- | Required Indicates where the journey started. This is also known as the "From Location". Maximum length: 100 characters |
UnitOfMeasure |
string |
- | Required The unit of measure for distance and odometer values. Supported values: M - miles, K - kilometers |
NOTE: Clients that have Car Configurations that include variable rates or custom mileage expense type codes are not supported. We only support Car Configurations that include Personal Car One-Rate definitions, using the default mileage expense type code (MILEG) where Google Maps is not set as mandatory.
Expense Form Field
The configured fields for the specified expense form.
Version
1.1
URI
https://www.concursolutions.com/api/expense/expensereport/v1.1/report/Form/_{FormId}_/Fields
Operations
Get a List of Form Fields
Retrieves the details of the configured form fields for the specified form.
NOTE: When sending in requests using these fields, be sure to include the required fields from the form and any additional required fields specified in the request documentation.
Request
Request Parameters
| Parameter | Required/Optional | Description |
|---|---|---|
| {FormId}/Fields | required | The unique identifier for the desired form and the Fields keyword. |
Example: https://www.concursolutions.com/api/expense/expensereport/v1.1/report/Form/{FormId}/Fields
URI Source: The FormId is returned in the FormId element by the Get Form Data function.
Headers
Authorization Header
Authorization header with OAuth token for valid SAP Concur user. Required.
Accept Header
application/xml
Response
Response Schema
This request will return a FormFieldsList parent element with a FormField parent element for each configured form field.
FormField Elements
| Element | Description |
|---|---|
| Id | The form field ID. |
| Label | The form field label. |
| ControlType | The type of field. |
| DataType | The type of data accepted by the field. |
| MaxLength | The maximum length of the field value. |
| Required | Whether the field is required. |
| Cols | The number of columns the field contains. |
| Access | The access level the specified user has to the field. |
| Width | The width of the field. |
| Custom | Whether the field is custom. |
| Sequence | The field order on the form. |
XML Example Request
GET https://www.concursolutions.com/api/expense/expensereport/v1.1/report/Form/nAaT8$puKKO2$pEVlsXfSruLpDfZL0wVM$s7/Fields HTTP/1.1
Authorization: OAuth {access token}
...
XML Example of Successful Response
HTTP/1.1 200 OK
Content-Type: application/xml
<FormFieldsList xmlns="https://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<FormField>
<Id>Name</Id>
<Label>ReportName</Label>
<ControlType>edit</ControlType>
<DataType>VARCHAR</DataType>
<MaxLength>32</MaxLength>
<Required>Y</Required>
<Cols>32</Cols>
<Access>RW</Access>
<Width>32</Width>
<Custom>N</Custom>
<Sequence>1</Sequence>
</FormField>
<FormField>
<Id>ReportId</Id>
<Label>ReportID</Label>
<ControlType>static</ControlType>
<DataType>VARCHAR</DataType>
<MaxLength>32</MaxLength>
<Required>Y</Required>
<Cols />
<Access>RO</Access>
<Width />
<Custom>N</Custom>
<Sequence>2</Sequence>
</FormField>
<FormField>
<Id>PolKey</Id>
<Label>Policy</Label>
<ControlType>picklist</ControlType>
<DataType>INTEGER</DataType>
<MaxLength />
<Required>Y</Required>
<Cols />
<Access>RW</Access>
<Width />
<Custom>N</Custom>
<Sequence>3</Sequence>
</FormField>
<FormField>
<Id>EmpName</Id>
<Label>EmployeeName</Label>
<ControlType>static</ControlType>
<DataType>VARCHAR</DataType>
<MaxLength>32</MaxLength>
<Required>Y</Required>
<Cols />
<Access>HD</Access>
<Width />
<Custom>N</Custom>
<Sequence>4</Sequence>
</FormField>
<FormField>
<Id>UserDefinedDate</Id>
<Label>ReportDate</Label>
<ControlType>edit</ControlType>
<DataType>TIMESTAMP</DataType>
<MaxLength />
<Required>N</Required>
<Cols />
<Access>RW</Access>
<Width />
<Custom>N</Custom>
<Sequence>5</Sequence>
</FormField>
<FormField>
<Id>Purpose</Id>
<Label>BusinessPurpose</Label>
<ControlType>textarea</ControlType>
<DataType>VARCHAR</DataType>
<MaxLength>500</MaxLength>
<Required>Y</Required>
<Cols>32</Cols>
<Access>RW</Access>
<Width>32</Width>
<Custom>N</Custom>
<Sequence>6</Sequence>
</FormField>
</FormFieldsList>
Expense Form
The configured expense forms in SAP Concur. Clients can have multiple forms configured for each form type.
Version
1.1
URI
https://www.concursolutions.com/api/expense/expensereport/v1.1/report/Forms/
Operations
Get Form Types
Retrieves the list of configured form types.
Request
Request Parameters
None.
Headers
Authorization Header
Authorization header with OAuth token for valid SAP Concur user. Required.
Accept Header
application/xml
Response
Get Form Types Schema
This request will return a FormTypesList parent element with a FormType parent element for each configured form.
FormType Elements
| Element | Description |
|---|---|
| Name | The form type name. |
| FormCode | The form type code. |
Examples
XML Example Request
GET https://www.concursolutions.com/api/expense/expensereport/v1.1/report/Forms HTTP/1.1
Authorization: OAuth {access token}
...
XML Example of Successful Response
HTTP/1.1 200 OK
Content-Type: application/xml
<FormTypesList
xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03"
xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<FormType>
<Name>Expense Entry</Name>
<FormCode>ENTRYINFO</FormCode>
</FormType>
<FormType>
<Name>Expense Report Header</Name>
<FormCode>RPTINFO</FormCode>
</FormType>
<FormType>
<Name>Expense Allocation</Name>
<FormCode>ALLOCINFO</FormCode>
</FormType>
<FormType>
<Name>Expense Attendee</Name>
<FormCode>ATTNINFO</FormCode>
</FormType>
<FormType>
<Name>Authorization Request Expense Category</Name>
<FormCode>TRAVELREQENTRYINFO</FormCode>
</FormType>
<FormType>
<Name>Authorization Request Header</Name>
<FormCode>TRAVELREQINFO</FormCode>
</FormType>
<FormType>
<Name>Expense Detail View</Name>
<FormCode>EXPLISTDTL</FormCode>
</FormType>
<FormType>
<Name>Attendee Detail View</Name>
<FormCode>ATNLISTDTL</FormCode>
</FormType>
<FormType>
<Name>Expense Car</Name>
<FormCode>CARINFO</FormCode>
</FormType>
</FormTypesList>
Get Form Data
Retrieves the list of configured forms for the specified form type.
Request
Request Parameters
| Parameter | Required/Optional | Description |
|---|---|---|
| FormCode | required | The identifier for the desired form. |
Example: https://www.concursolutions.com/api/expense/expensereport/v1.1/report/Forms/{FormCode}
URI Source: The FormCode is returned in the FormCode element in the Get Form Types response.
Headers
Authorization Header
Authorization header with OAuth token for valid SAP Concur user.
Accept Header
application/xml
Response
Get Form Data Schema
This request will return a FormDataList parent element with a FormData parent element for each configured form.
FormData Elements
| Element | Description |
|---|---|
| Name | The form name. |
| FormId | The form identifier. |
Examples
XML Example Request
GET https://www.concursolutions.com/api/expense/expensereport/v1.1/report/Forms/RPTINFO HTTP/1.1
Authorization: OAuth {access token}
...
XML Example of Successful Response
HTTP/1.1 200 OK
Content-Type: application/xml
<FormDataList xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<FormData>
<Name>Central Reconciliation Columns</Name>
<FormId>nAaT8$puKKOG5E4R9gCMyXVrFjo9NIbmQl</FormId>
</FormData>
<FormData>
<Name>Central Reconciliation Report</Name>
<FormId>nAaT8$puKKOGmK3xvAdnAOgJ9fxaoXjyW$s</FormId>
</FormData>
<FormData>
<Name>Default Report Information</Name>
<FormId>nAaT8$puKKO2$pEVlsXfSruLpDfZL0wVM$s7</FormId>
</FormData>
</FormDataList>
Expense Group Configurations
Expense Group Configurations
Retrieves the list of Expense Polices, Expense Types and Payment Types for the Expense Group the user specified in the OAuth access token is assigned to. Each Expense Policy contains a list of valid Expense Types. The Payment Types are associated with the user’s Expense Group and apply to all the returned policies. Only the payment types that are valid for the Post Expense Entry endpoint are returned.
NOTE: The Concur Expense product is highly configurable, and each client may have a unique set of payment types. If a payment type is not included in the response, it is not available for use with this client.
- Retrieve a configuration of an expense group
- Retrieve an expense group configuration by ID
- Schema
- Make a test call using 3.0 Swagger
Version
3.0
1.1 documentation is available here
Retrieve a configuration of an expense group
GET /api/v3.0/expense/expensegroupconfigurations
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
user |
string |
query |
The login ID of the user associated with this expense group configuration. The user must have the Web Services Admin role to use this parameter. |
offset |
string |
query |
The starting point of the next set of results, after the limit specified in the limit field has been reached. |
limit |
Int32 |
query |
The number of records to return Default value: 10 |
Request URL
https://www.concursolutions.com/api/v3.0/expense/expensegroupconfigurations?user=ALL&limit=10
JSON example of a successful response
{
"Items": [
{
"Name": "United Kingdom",
"AttendeeListFormID": "gWh2aF2cfwJElRBMIJ9ahYnTVXDIp1fQUdg",
"AttendeeListFormName": "Default Attendee Detail View",
"AllowUserRegisterYodlee": false,
"AllowUserDigitalTaxInvoice": false,
"CashAdvance": null,
"PaymentTypes": [
{
"ID": "gWurF7TC$pQAT4cqT0JokiYMobzQdz",
"Name": "Cash",
"IsDefault": false
},
{
"ID": "gWurL7jy84a4BAdqGaTNrtiABiqpM",
"Name": "Company Paid",
"IsDefault": false
},
{
"ID": "gWvnH$pTyEPYFerdCk8rjvoSpmM4L0",
"Name": "Pending Card Transaction",
"IsDefault": false
}
],
"Policies": [
{
"ID": "gWmINGEAkRfLbo7HmBh5USB3$pS8HMWDoP2Q",
"Name": "*Global Expense Policy",
"IsDefault": false,
"IsInheritable": true,
"ExpenseTypes": [
{
"Code": "LODNG",
"Name": "Hotel",
"ExpenseCode": "LODGING"
}
]
}
]
}
]
}
Retrieve an expense group configuration by ID
GET /api/v3.0/expense/expensegroupconfigurations/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required The ID of the expense group configuration. |
user |
string |
query |
The login ID of the user associated with this expense group configuration. The user must have the Web Services Admin role to use this parameter. |
Schema
Expense Group Configurations
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required The ID of the expense group configuration. |
user |
string |
query |
The login ID of the user associated with this expense group configuration. The user must have the Web Services Admin role to use this parameter. |
Expense Group Configuration
| Name | Type | Format | Description |
|---|---|---|---|
AllowUserDigitalTaxInvoice |
Boolean |
- | Indicates whether users are allowed to upload digital tax invoices. Format: true or false |
AllowUserRegisterYodlee |
Boolean |
- | Indicates whether users in the expense group are allowed to register Yodlee credit cards. Format: true or false |
AttendeeListFormID |
string |
- | The unique identifier for the attendee list form. |
AttendeeListFormName |
string |
- | The name of the attendee list form. |
AttendeeTypes |
array[AttendeeType] |
- | The list of attendee types. |
CashAdvance |
CashAdvance |
- | The amount of the cash advance. |
ID |
string |
- | The unique identifier of the resource. |
Name |
string |
- | The name of the expense group configuration. |
PaymentTypes |
array |
Payment Type | The list of payment types. |
Policies |
array |
Policy | The list of policies and expense types. |
URI |
string |
- | The URI to the resource. |
Attendee Type
| Name | Type | Format | Description |
|---|---|---|---|
Code |
string |
- | The attendee type code. |
Name |
string |
- | The name of the attendee type. |
Cash Advance
| Name | Type | Format | Description |
|---|---|---|---|
AllowUserCarryBalance |
Boolean |
- | Indicates whether users are allowed to carry a cash advance balance forward from one report to another. Format: true or false |
AllowUserLinkMultiple |
Boolean |
- | Indicates whether users are allowed to link multiple cash advances to one expense report. Format: true or false |
AllowUserUpdateExchangeRate |
Boolean |
- | Indicates whether users are allowed to update the currency exchange rate for expense entries. Format: true or false |
Name |
string |
- | The name of the cash advance workflow. |
WorkflowID |
string |
- | The unique identifier for the cash advance workflow. Null means there is no such workflow. |
Payment Type
| Name | Type | Format | Description |
|---|---|---|---|
ID |
string |
- | The unique identifier of the resource. |
IsDefault |
Boolean |
- | Determines whether this payment type is the default. Format: true or false |
Name |
string |
- | The name of the payment type. |
Policy
| Name | Type | Format | Description |
|---|---|---|---|
ExpenseTypes |
array |
ExpenseType | The parent element for the list of expense types in the policy. |
ID |
string |
- | The unique identifier of the resource. |
IsDefault |
Boolean |
- | Indicates whether this policy is the default. Format: true or false |
IsInheritable |
Boolean |
- | Indicates whether the descendent nodes in the Expense Feature Hierarchy are covered by this policy. Format: true or false |
Name |
string |
- | The name of the policy. |
Expense Type
| Name | Type | Format | Description |
|---|---|---|---|
Code |
string |
- | The code for the expense type. Expense types define expenses within an expense category. For example, Business Meal is an expense type in the MEALS category. |
ExpenseCode |
string |
- | The code for the expense category. The expense category code controls the function of an expense entry. Format: OTHER - Standard, COCARMILE - Company Car, PCARMILE - Personal Car, MFUEL - Fuel For Mileage, LODGING - Lodging, MEALS - Meals, OTHERNP - Other Not Partially Approvable, JPYPTRAN - Japanese Public Transportation |
Name |
string |
- | The name of the expense type. |
Request URL
https://www.concursolutions.com/api/v3.0/expense/expensegroupconfigurations/gWv5bj%24sPY1weV9audTTRp7PkBlea3Y6aizg
JSON example of a successful response
{
"Name": "United Kingdom",
"AttendeeListFormID": "gWh2aF2cfwJElRBMIJ9ahYnTVXDIp1fQUdg",
"AttendeeListFormName": "Default Attendee Detail View",
"AllowUserRegisterYodlee": false,
"AllowUserDigitalTaxInvoice": false,
"CashAdvance": null,
"PaymentTypes": [
{
"ID": "gWurF7TC$pQAT4cqT0JokiYMobzQdz",
"Name": "Cash",
"IsDefault": false
},
{
"ID": "gWurL7jy84a4BAdqGaTNrtiABiqpM",
"Name": "Company Paid",
"IsDefault": false
},
{
"ID": "gWvnH$pTyEPYFerdCk8rjvoSpmM4L0",
"Name": "Pending Card Transaction",
"IsDefault": false
}
],
"Policies": [
{
"ID": "gWmINGEAkRfLbo7HmBh5USB3$pS8HMWDoP2Q",
"Name": "*Global Expense Policy",
"IsDefault": false,
"IsInheritable": true,
"ExpenseTypes": [
{
"Code": "LODNG",
"Name": "Hotel",
"ExpenseCode": "LODGING"
},
{
"Code": "LODTX",
"Name": "Hotel Tax",
"ExpenseCode": "LODGING"
},
{
"Code": "LNDRY",
"Name": "Laundry",
"ExpenseCode": "OTHER"
},
{
"Code": "AIRFR",
"Name": "Airfare",
"ExpenseCode": "OTHER"
},
{
"Code": "01026",
"Name": "Airline Fees",
"ExpenseCode": "OTHER"
},
{
"Code": "CARRT",
"Name": "Car Rental",
"ExpenseCode": "OTHER"
},
{
"Code": "CARMI",
"Name": "Company Car Mileage",
"ExpenseCode": "COCARMILE"
},
{
"Code": "GASXX",
"Name": "Fuel",
"ExpenseCode": "OTHER"
},
{
"Code": "PARKG",
"Name": "Parking",
"ExpenseCode": "OTHER"
},
{
"Code": "MILEG",
"Name": "Personal Car Mileage",
"ExpenseCode": "PCARMILE"
},
{
"Code": "TRAIN",
"Name": "Public Transport",
"ExpenseCode": "OTHER"
},
{
"Code": "TAXIX",
"Name": "Taxi",
"ExpenseCode": "OTHER"
},
{
"Code": "TOLLS",
"Name": "Tolls/Road Charges",
"ExpenseCode": "OTHER"
},
{
"Code": "01025",
"Name": "Train",
"ExpenseCode": "OTHER"
},
{
"Code": "BRKFT",
"Name": "Breakfast",
"ExpenseCode": "OTHER"
},
{
"Code": "DINNR",
"Name": "Dinner",
"ExpenseCode": "OTHER"
},
{
"Code": "01028",
"Name": "Individual Meals",
"ExpenseCode": "OTHER"
},
{
"Code": "LUNCH",
"Name": "Lunch",
"ExpenseCode": "OTHER"
},
{
"Code": "BUSML",
"Name": "Entertainment - Clients",
"ExpenseCode": "OTHER"
},
{
"Code": "01004",
"Name": "Entertainment - Staff",
"ExpenseCode": "OTHER"
},
{
"Code": "01005",
"Name": "Courier/Shipping/Freight",
"ExpenseCode": "OTHER"
},
{
"Code": "OFCSP",
"Name": "Office Equipment/Hardware",
"ExpenseCode": "OTHER"
},
{
"Code": "01007",
"Name": "Office Supplies/Software",
"ExpenseCode": "OTHER"
},
{
"Code": "POSTG",
"Name": "Postage",
"ExpenseCode": "OTHER"
},
{
"Code": "01006",
"Name": "Printing/Photocopying/Stationery",
"ExpenseCode": "OTHER"
},
{
"Code": "01035",
"Name": "Business Calls",
"ExpenseCode": "OTHER"
},
{
"Code": "ONLIN",
"Name": "Internet/Online Fees",
"ExpenseCode": "OTHER"
},
{
"Code": "CELPH",
"Name": "Mobile/Cellular Phone",
"ExpenseCode": "OTHER"
},
{
"Code": "01036",
"Name": "Non-Business Calls",
"ExpenseCode": "OTHER"
},
{
"Code": "LOCPH",
"Name": "Telephone/Fax",
"ExpenseCode": "OTHER"
},
{
"Code": "BANKF",
"Name": "Bank Fees",
"ExpenseCode": "OTHER"
},
{
"Code": "01024",
"Name": "Currency Exchange Fees",
"ExpenseCode": "OTHER"
},
{
"Code": "01011",
"Name": "Medical Fees",
"ExpenseCode": "OTHER"
},
{
"Code": "01008",
"Name": "Passports/Visa Fees",
"ExpenseCode": "OTHER"
},
{
"Code": "AWRDS",
"Name": "Gifts - Clients",
"ExpenseCode": "OTHER"
},
{
"Code": "GIFTS",
"Name": "Gifts - Staff",
"ExpenseCode": "OTHER"
},
{
"Code": "TRDSH",
"Name": "Marketing/Promotional Costs",
"ExpenseCode": "OTHER"
},
{
"Code": "MISCL",
"Name": "Miscellaneous",
"ExpenseCode": "OTHER"
},
{
"Code": "01014",
"Name": "Newspapers/Magazines/Books",
"ExpenseCode": "OTHER"
},
{
"Code": "DUESX",
"Name": "Professional Subscriptions/Dues",
"ExpenseCode": "OTHER"
},
{
"Code": "SEMNR",
"Name": "Seminar/Course fees",
"ExpenseCode": "OTHER"
},
{
"Code": "01009",
"Name": "Tips/Gratuities",
"ExpenseCode": "OTHER"
},
{
"Code": "01012",
"Name": "Tuition/Training Reimbursement",
"ExpenseCode": "OTHER"
},
{
"Code": "01010",
"Name": "Ex Pat Expenses",
"ExpenseCode": "OTHER"
},
{
"Code": "01017",
"Name": "Relocation Expenses",
"ExpenseCode": "OTHER"
},
{
"Code": "CSHRN",
"Name": "Cash Advance Return",
"ExpenseCode": "OTHERNP"
},
{
"Code": "CURGL",
"Name": "Currency Gain/Loss",
"ExpenseCode": "OTHERNP"
},
{
"Code": "01052",
"Name": "Fixed Vehicle Reimbursement",
"ExpenseCode": "OTHER"
},
{
"Code": "01053",
"Name": "Motus Other Amount",
"ExpenseCode": "OTHER"
},
{
"Code": "01054",
"Name": "Variable Vehicle Reimbursement",
"ExpenseCode": "OTHER"
}
]
},
{
"ID": "gWmINGEAkRfGsCKjw8DAec1dbfF$pV$sxbfpw",
"Name": "Germany Expense Policy",
"IsDefault": null,
"IsInheritable": null,
"ExpenseTypes": [
{
"Code": "LODNG",
"Name": "Hotel",
"ExpenseCode": "LODGING"
},
{
"Code": "LODTX",
"Name": "Hotel Tax",
"ExpenseCode": "LODGING"
},
{
"Code": "LNDRY",
"Name": "Laundry",
"ExpenseCode": "OTHER"
},
{
"Code": "AIRFR",
"Name": "Airfare",
"ExpenseCode": "OTHER"
},
{
"Code": "01026",
"Name": "Airline Fees",
"ExpenseCode": "OTHER"
},
{
"Code": "01002",
"Name": "Car Maintenance/Repairs ",
"ExpenseCode": "OTHER"
},
{
"Code": "CARRT",
"Name": "Car Rental",
"ExpenseCode": "OTHER"
},
{
"Code": "GASXX",
"Name": "Fuel",
"ExpenseCode": "OTHER"
},
{
"Code": "PARKG",
"Name": "Parking",
"ExpenseCode": "OTHER"
},
{
"Code": "MILEG",
"Name": "Personal Car Mileage",
"ExpenseCode": "PCARMILE"
},
{
"Code": "TRAIN",
"Name": "Public Transport",
"ExpenseCode": "OTHER"
},
{
"Code": "TAXIX",
"Name": "Taxi",
"ExpenseCode": "OTHER"
},
{
"Code": "TOLLS",
"Name": "Tolls/Road Charges",
"ExpenseCode": "OTHER"
},
{
"Code": "01025",
"Name": "Train",
"ExpenseCode": "OTHER"
},
{
"Code": "BRKFT",
"Name": "Breakfast",
"ExpenseCode": "OTHER"
},
{
"Code": "DINNR",
"Name": "Dinner",
"ExpenseCode": "OTHER"
},
{
"Code": "LUNCH",
"Name": "Lunch",
"ExpenseCode": "OTHER"
},
{
"Code": "01055",
"Name": "EBR 1190",
"ExpenseCode": "OTHER"
},
{
"Code": "01030",
"Name": "Entertainment - External (Domestic)",
"ExpenseCode": "OTHER"
},
{
"Code": "01031",
"Name": "Entertainment - External (Foreign)",
"ExpenseCode": "OTHER"
},
{
"Code": "01004",
"Name": "Entertainment - Staff",
"ExpenseCode": "OTHER"
},
{
"Code": "01005",
"Name": "Courier/Shipping/Freight",
"ExpenseCode": "OTHER"
},
{
"Code": "OFCSP",
"Name": "Office Equipment/Hardware",
"ExpenseCode": "OTHER"
},
{
"Code": "01007",
"Name": "Office Supplies/Software",
"ExpenseCode": "OTHER"
},
{
"Code": "POSTG",
"Name": "Postage",
"ExpenseCode": "OTHER"
},
{
"Code": "01006",
"Name": "Printing/Photocopying/Stationery",
"ExpenseCode": "OTHER"
},
{
"Code": "01035",
"Name": "Business Calls",
"ExpenseCode": "OTHER"
},
{
"Code": "ONLIN",
"Name": "Internet/Online Fees",
"ExpenseCode": "OTHER"
},
{
"Code": "CELPH",
"Name": "Mobile/Cellular Phone",
"ExpenseCode": "OTHER"
},
{
"Code": "01036",
"Name": "Non-Business Calls",
"ExpenseCode": "OTHER"
},
{
"Code": "LOCPH",
"Name": "Telephone/Fax",
"ExpenseCode": "OTHER"
},
{
"Code": "BANKF",
"Name": "Bank Fees",
"ExpenseCode": "OTHER"
},
{
"Code": "01024",
"Name": "Currency Exchange Fees",
"ExpenseCode": "OTHER"
},
{
"Code": "01011",
"Name": "Medical Fees",
"ExpenseCode": "OTHER"
},
{
"Code": "01008",
"Name": "Passports/Visa Fees",
"ExpenseCode": "OTHER"
},
{
"Code": "01033",
"Name": "Gifts <= 35€",
"ExpenseCode": "OTHER"
},
{
"Code": "01032",
"Name": "Gifts > 35€",
"ExpenseCode": "OTHER"
},
{
"Code": "TRDSH",
"Name": "Marketing/Promotional Costs",
"ExpenseCode": "OTHER"
},
{
"Code": "MISCL",
"Name": "Miscellaneous",
"ExpenseCode": "OTHER"
},
{
"Code": "01014",
"Name": "Newspapers/Magazines/Books",
"ExpenseCode": "OTHER"
},
{
"Code": "DUESX",
"Name": "Professional Subscriptions/Dues",
"ExpenseCode": "OTHER"
},
{
"Code": "SEMNR",
"Name": "Seminar/Course fees",
"ExpenseCode": "OTHER"
},
{
"Code": "01009",
"Name": "Tips/Gratuities",
"ExpenseCode": "OTHER"
},
{
"Code": "01012",
"Name": "Tuition/Training Reimbursement",
"ExpenseCode": "OTHER"
},
{
"Code": "01010",
"Name": "Ex Pat Expenses",
"ExpenseCode": "OTHER"
},
{
"Code": "01017",
"Name": "Relocation Expenses",
"ExpenseCode": "OTHER"
},
{
"Code": "CSHRN",
"Name": "Cash Advance Return",
"ExpenseCode": "OTHERNP"
},
{
"Code": "CURGL",
"Name": "Currency Gain/Loss",
"ExpenseCode": "OTHERNP"
}
]
},
{
"ID": "gWmINGEAkQoarrf1JiyI8$sqI$s00T30OfIlA",
"Name": "Italy Expense Policy",
"IsDefault": null,
"IsInheritable": null,
"ExpenseTypes": [
{
"Code": "LODNG",
"Name": "Hotel",
"ExpenseCode": "LODGING"
},
{
"Code": "LODTX",
"Name": "Hotel Tax",
"ExpenseCode": "LODGING"
},
{
"Code": "LNDRY",
"Name": "Laundry",
"ExpenseCode": "OTHER"
},
{
"Code": "AIRFR",
"Name": "Airfare",
"ExpenseCode": "OTHER"
},
{
"Code": "01026",
"Name": "Airline Fees",
"ExpenseCode": "OTHER"
},
{
"Code": "01002",
"Name": "Car Maintenance/Repairs ",
"ExpenseCode": "OTHER"
},
{
"Code": "CARRT",
"Name": "Car Rental",
"ExpenseCode": "OTHER"
},
{
"Code": "GASXX",
"Name": "Fuel",
"ExpenseCode": "OTHER"
},
{
"Code": "PARKG",
"Name": "Parking",
"ExpenseCode": "OTHER"
},
{
"Code": "MILEG",
"Name": "Personal Car Mileage",
"ExpenseCode": "PCARMILE"
},
{
"Code": "TRAIN",
"Name": "Public Transport",
"ExpenseCode": "OTHER"
},
{
"Code": "TAXIX",
"Name": "Taxi",
"ExpenseCode": "OTHER"
},
{
"Code": "TOLLS",
"Name": "Tolls/Road Charges",
"ExpenseCode": "OTHER"
},
{
"Code": "01025",
"Name": "Train",
"ExpenseCode": "OTHER"
},
{
"Code": "01043",
"Name": "Alcoholic Beverages & Softs Drinks",
"ExpenseCode": "MEALS"
},
{
"Code": "BRKFT",
"Name": "Breakfast",
"ExpenseCode": "OTHER"
},
{
"Code": "DINNR",
"Name": "Dinner",
"ExpenseCode": "OTHER"
},
{
"Code": "01028",
"Name": "Individual Meals",
"ExpenseCode": "OTHER"
},
{
"Code": "01044",
"Name": "Individual Meals - Within Municipality",
"ExpenseCode": "MEALS"
},
{
"Code": "LUNCH",
"Name": "Lunch",
"ExpenseCode": "OTHER"
},
{
"Code": "BUSML",
"Name": "Entertainment - Clients",
"ExpenseCode": "OTHER"
},
{
"Code": "01004",
"Name": "Entertainment - Staff",
"ExpenseCode": "OTHER"
},
{
"Code": "01005",
"Name": "Courier/Shipping/Freight",
"ExpenseCode": "OTHER"
},
{
"Code": "OFCSP",
"Name": "Office Equipment/Hardware",
"ExpenseCode": "OTHER"
},
{
"Code": "POSTG",
"Name": "Postage",
"ExpenseCode": "OTHER"
},
{
"Code": "01006",
"Name": "Printing/Photocopying/Stationery",
"ExpenseCode": "OTHER"
},
{
"Code": "01035",
"Name": "Business Calls",
"ExpenseCode": "OTHER"
},
{
"Code": "ONLIN",
"Name": "Internet/Online Fees",
"ExpenseCode": "OTHER"
},
{
"Code": "CELPH",
"Name": "Mobile/Cellular Phone",
"ExpenseCode": "OTHER"
},
{
"Code": "01036",
"Name": "Non-Business Calls",
"ExpenseCode": "OTHER"
},
{
"Code": "LOCPH",
"Name": "Telephone/Fax",
"ExpenseCode": "OTHER"
},
{
"Code": "BANKF",
"Name": "Bank Fees",
"ExpenseCode": "OTHER"
},
{
"Code": "01024",
"Name": "Currency Exchange Fees",
"ExpenseCode": "OTHER"
},
{
"Code": "01008",
"Name": "Passports/Visa Fees",
"ExpenseCode": "OTHER"
},
{
"Code": "AWRDS",
"Name": "Gifts - Clients",
"ExpenseCode": "OTHER"
},
{
"Code": "GIFTS",
"Name": "Gifts - Staff",
"ExpenseCode": "OTHER"
},
{
"Code": "TRDSH",
"Name": "Marketing/Promotional Costs",
"ExpenseCode": "OTHER"
},
{
"Code": "01014",
"Name": "Newspapers/Magazines/Books",
"ExpenseCode": "OTHER"
},
{
"Code": "DUESX",
"Name": "Professional Subscriptions/Dues",
"ExpenseCode": "OTHER"
},
{
"Code": "SEMNR",
"Name": "Seminar/Course fees",
"ExpenseCode": "OTHER"
},
{
"Code": "01009",
"Name": "Tips/Gratuities",
"ExpenseCode": "OTHER"
},
{
"Code": "01012",
"Name": "Tuition/Training Reimbursement",
"ExpenseCode": "OTHER"
},
{
"Code": "01045",
"Name": "Undocumented Incidentals - Domestic",
"ExpenseCode": "OTHER"
},
{
"Code": "01046",
"Name": "Undocumented Incidentals - International",
"ExpenseCode": "OTHER"
},
{
"Code": "CSHRN",
"Name": "Cash Advance Return",
"ExpenseCode": "OTHERNP"
},
{
"Code": "CURGL",
"Name": "Currency Gain/Loss",
"ExpenseCode": "OTHERNP"
}
]
},
{
"ID": "gWmINGEAkQoapyOLKfSdm0A9qK0ZVUvwolA",
"Name": "US Expense Policy",
"IsDefault": null,
"IsInheritable": null,
"ExpenseTypes": [
{
"Code": "LODNG",
"Name": "Hotel",
"ExpenseCode": "LODGING"
},
{
"Code": "LODTX",
"Name": "Hotel Tax",
"ExpenseCode": "LODGING"
},
{
"Code": "INCTS",
"Name": "Incidentals",
"ExpenseCode": "OTHER"
},
{
"Code": "LNDRY",
"Name": "Laundry",
"ExpenseCode": "OTHER"
},
{
"Code": "01057",
"Name": "Test4",
"ExpenseCode": "OTHER"
},
{
"Code": "AIRFR",
"Name": "Airfare",
"ExpenseCode": "OTHER"
},
{
"Code": "01026",
"Name": "Airline Fees",
"ExpenseCode": "OTHER"
},
{
"Code": "01002",
"Name": "Car Maintenance/Repairs ",
"ExpenseCode": "OTHER"
},
{
"Code": "CARRT",
"Name": "Car Rental",
"ExpenseCode": "OTHER"
},
{
"Code": "CARMI",
"Name": "Company Car Mileage",
"ExpenseCode": "COCARMILE"
},
{
"Code": "GASXX",
"Name": "Fuel",
"ExpenseCode": "OTHER"
},
{
"Code": "PARKG",
"Name": "Parking",
"ExpenseCode": "OTHER"
},
{
"Code": "MILEG",
"Name": "Personal Car Mileage",
"ExpenseCode": "PCARMILE"
},
{
"Code": "TRAIN",
"Name": "Public Transport",
"ExpenseCode": "OTHER"
},
{
"Code": "TAXIX",
"Name": "Taxi",
"ExpenseCode": "OTHER"
},
{
"Code": "TOLLS",
"Name": "Tolls/Road Charges",
"ExpenseCode": "OTHER"
},
{
"Code": "01025",
"Name": "Train",
"ExpenseCode": "OTHER"
},
{
"Code": "BRKFT",
"Name": "Breakfast",
"ExpenseCode": "OTHER"
},
{
"Code": "01027",
"Name": "Business Meals (Attendees)",
"ExpenseCode": "OTHER"
},
{
"Code": "DINNR",
"Name": "Dinner",
"ExpenseCode": "OTHER"
},
{
"Code": "LUNCH",
"Name": "Lunch",
"ExpenseCode": "OTHER"
},
{
"Code": "BUSML",
"Name": "Entertainment - Clients",
"ExpenseCode": "OTHER"
},
{
"Code": "01004",
"Name": "Entertainment - Staff",
"ExpenseCode": "OTHER"
},
{
"Code": "01005",
"Name": "Courier/Shipping/Freight",
"ExpenseCode": "OTHER"
},
{
"Code": "OFCSP",
"Name": "Office Equipment/Hardware",
"ExpenseCode": "OTHER"
},
{
"Code": "01007",
"Name": "Office Supplies/Software",
"ExpenseCode": "OTHER"
},
{
"Code": "POSTG",
"Name": "Postage",
"ExpenseCode": "OTHER"
},
{
"Code": "01006",
"Name": "Printing/Photocopying/Stationery",
"ExpenseCode": "OTHER"
},
{
"Code": "01035",
"Name": "Business Calls",
"ExpenseCode": "OTHER"
},
{
"Code": "ONLIN",
"Name": "Internet/Online Fees",
"ExpenseCode": "OTHER"
},
{
"Code": "CELPH",
"Name": "Mobile/Cellular Phone",
"ExpenseCode": "OTHER"
},
{
"Code": "01036",
"Name": "Non-Business Calls",
"ExpenseCode": "OTHER"
},
{
"Code": "LOCPH",
"Name": "Telephone/Fax",
"ExpenseCode": "OTHER"
},
{
"Code": "01047",
"Name": "Agency Booking Fees",
"ExpenseCode": "OTHER"
},
{
"Code": "BANKF",
"Name": "Bank Fees",
"ExpenseCode": "OTHER"
},
{
"Code": "01024",
"Name": "Currency Exchange Fees",
"ExpenseCode": "OTHER"
},
{
"Code": "01008",
"Name": "Passports/Visa Fees",
"ExpenseCode": "OTHER"
},
{
"Code": "AWRDS",
"Name": "Gifts - Clients",
"ExpenseCode": "OTHER"
},
{
"Code": "GIFTS",
"Name": "Gifts - Staff",
"ExpenseCode": "OTHER"
},
{
"Code": "TRDSH",
"Name": "Marketing/Promotional Costs",
"ExpenseCode": "OTHER"
},
{
"Code": "MISCL",
"Name": "Miscellaneous",
"ExpenseCode": "OTHER"
},
{
"Code": "01014",
"Name": "Newspapers/Magazines/Books",
"ExpenseCode": "OTHER"
},
{
"Code": "DUESX",
"Name": "Professional Subscriptions/Dues",
"ExpenseCode": "OTHER"
},
{
"Code": "SEMNR",
"Name": "Seminar/Course fees",
"ExpenseCode": "OTHER"
},
{
"Code": "01038",
"Name": "Staff Awards/Incentives",
"ExpenseCode": "OTHER"
},
{
"Code": "01009",
"Name": "Tips/Gratuities",
"ExpenseCode": "OTHER"
},
{
"Code": "01012",
"Name": "Tuition/Training Reimbursement",
"ExpenseCode": "OTHER"
},
{
"Code": "CSHRN",
"Name": "Cash Advance Return",
"ExpenseCode": "OTHERNP"
},
{
"Code": "CURGL",
"Name": "Currency Gain/Loss",
"ExpenseCode": "OTHERNP"
},
{
"Code": "01052",
"Name": "Fixed Vehicle Reimbursement",
"ExpenseCode": "OTHER"
},
{
"Code": "01053",
"Name": "Motus Other Amount",
"ExpenseCode": "OTHER"
},
{
"Code": "01054",
"Name": "Variable Vehicle Reimbursement",
"ExpenseCode": "OTHER"
}
]
}
],
"AttendeeTypes": [
{
"Code": "PRIVATE",
"Name": "Attendee-Private List"
},
{
"Code": "HCOCGDM",
"Name": "Cegedim HCO Search–OneKey US"
}
],
"ID": "gWv5bj$sPY1weV9audTTRp7PkBlea3Y6aizg",
"URI": "https://www.concursolutions.com/api/v3.0/expense/expensegroupconfigurations/gWv5bj$sPY1weV9audTTRp7PkBlea3Y6aizg"
}
Itemizations
Itemizations
- Retrieve all expense itemizations owned by the user DEPRECATED: 05/19/2016 UNSUPPORTED: 11/19/2016
- Retrieve an expense itemization by ID
- Create a new expense itemization
- Update an expense itemization DEPRECATED: 05/19/2016 UNSUPPORTED: 11/19/2016
- Delete an expense itemization DEPRECATED: 05/19/2016 UNSUPPORTED: 11/19/2016
- Schema
Version
3.0 Note that some methods are deprecated
1.1 documentation is available here
Retrieve all expense itemizations owned by the user
DEPRECATED: 05/19/2016 UNSUPPORTED: 11/19/2016
GET /api/v3.0/expense/itemizations
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
reportID |
string |
query |
The report ID of the itemizations to be retrieved. Use the GET /expense/reportdigests function to find the report ID. Format: An alpha-numeric string |
entryID |
string |
query |
The entry ID for the itemizations to be retrieved. Use the GET /expense/entries endpoint to learn the valid entry ID. |
expenseTypeCode |
string |
query |
The expense type code for the itemizations to be retrieved. |
offset |
string |
query |
The starting point of the next set of results, after the limit specified in the limit field has been reached. |
limit |
Int32 |
query |
The number of records to return. Default value: 25 |
user |
string |
query |
The login ID of the user who owns the itemizations. The user must have the Web Services Admin role to use this parameter. |
Request URL
https://www.concursolutions.com/api/v3.0/expense/itemizations?limit=10&user=ALL
JSON example of a successful response
{
"Items": [
{
"EntryID": "gWidFO7ikXSy55WZOaAXv8JRfFkruCwrP4g",
"ReportID": "F4F027007E814C1CA70E",
"ReportOwnerID": "CAtraveler@concurconnect2.com",
"ExpenseTypeCode": "LODTX",
"ExpenseTypeName": "Hotel Tax",
"SpendCategoryCode": "LODGA",
"SpendCategoryName": "Lodging - Track Room Rate Spending",
"TransactionDate": "2013-08-07T00:00:00",
"TransactionAmount": 20,
"PostedAmount": 20,
"ApprovedAmount": 20,
"LocationID": "gWqWg2EhaUtcIW$s2pMbTGM8W81u2qcfX94w",
"LocationName": "Montreal, Quebec",
"LocationSubdivision": "Quebec",
"LocationCountry": "CA",
"Description": "test",
"IsPersonal": false,
"IsBillable": false,
"IsImageRequired": false,
"AllocationType": "N",
"HasComments": false,
"HasExceptions": false,
"LastModified": "2013-09-02T19:40:48.877",
"OrgUnit1": null,
"OrgUnit2": null,
"OrgUnit3": null,
"OrgUnit4": null,
"OrgUnit5": null,
"OrgUnit6": null,
"Custom1": null,
"Custom2": null,
"Custom3": null,
"Custom4": null,
"Custom5": null,
"Custom6": null,
"Custom7": null,
"Custom8": null,
"Custom9": null,
"Custom10": null,
"Custom11": null,
"Custom12": null,
"Custom13": null,
"Custom14": null,
"Custom15": null,
"Custom16": null,
"Custom17": null,
"Custom18": null,
"Custom19": null,
"Custom20": null,
"Custom21": null,
"Custom22": null,
"Custom23": null,
"Custom24": null,
"Custom25": null,
"Custom26": null,
"Custom27": null,
"Custom28": null,
"Custom29": null,
"Custom30": null,
"Custom31": null,
"Custom32": null,
"Custom33": null,
"Custom34": null,
"Custom35": null,
"Custom36": null,
"Custom37": null,
"Custom38": null,
"Custom39": null,
"Custom40": null,
"ID": "gWidFO7ikXSy$seMkLiQismjUIYkxYzCsf4g",
"URI": "https://www.concursolutions.com/api/v3.0/expense/itemizations/gWidFO7ikXSy$seMkLiQismjUIYkxYzCsf4g"
}
]
}
Retrieve an expense itemization by ID
GET /api/v3.0/expense/itemizations/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required The ID of the expense itemization. |
user |
string |
query |
The login ID of the user who owns the itemizations. The user must have the Web Services Admin role to use this parameter. |
Request URL
https://www.concursolutions.com/api/v3.0/expense/itemizations/gWidFO7ikXV6%24pcZsso2aBN0Aad4P5i8bjCg
JSON example of a successful response
{
"EntryID": "gWidFO7ikXV6$sQxTtWGQsIhawC4KoyssTCg",
"ReportID": "39BD9F7C5C3F4986A6A5",
"ReportOwnerID": "jimadmin@concurconnect2.com",
"ExpenseTypeCode": "LODTX",
"ExpenseTypeName": "Hotel Tax",
"SpendCategoryCode": "LODGA",
"SpendCategoryName": "Lodging - Track Room Rate Spending",
"TransactionDate": "2016-04-21T00:00:00",
"TransactionAmount": 20,
"PostedAmount": 20,
"ApprovedAmount": 20,
"LocationID": "gWqWg2EhcUKB$sottpx8eODvjn1$pWvWfG15A",
"LocationName": "Bellevue, Washington",
"LocationSubdivision": "Washington",
"LocationCountry": "US",
"Description": null,
"IsPersonal": false,
"IsBillable": false,
"IsImageRequired": false,
"AllocationType": "N",
"HasComments": false,
"HasExceptions": false,
"LastModified": "2016-04-22T22:19:55.213",
"OrgUnit1": null,
"OrgUnit2": null,
"OrgUnit3": null,
"OrgUnit4": null,
"OrgUnit5": null,
"OrgUnit6": null,
"Custom1": null,
"Custom2": null,
"Custom3": null,
"Custom4": null,
"Custom5": null,
"Custom6": null,
"Custom7": null,
"Custom8": null,
"Custom9": null,
"Custom10": null,
"Custom11": null,
"Custom12": null,
"Custom13": null,
"Custom14": null,
"Custom15": null,
"Custom16": null,
"Custom17": null,
"Custom18": null,
"Custom19": null,
"Custom20": null,
"Custom21": null,
"Custom22": null,
"Custom23": null,
"Custom24": null,
"Custom25": null,
"Custom26": null,
"Custom27": null,
"Custom28": null,
"Custom29": null,
"Custom30": null,
"Custom31": null,
"Custom32": null,
"Custom33": null,
"Custom34": null,
"Custom35": null,
"Custom36": null,
"Custom37": null,
"Custom38": null,
"Custom39": null,
"Custom40": null,
"ID": "gWidFO7ikXV6$pcZsso2aBN0Aad4P5i8bjCg",
"URI": "https://www.concursolutions.com/api/v3.0/expense/itemizations/gWidFO7ikXV6$pcZsso2aBN0Aad4P5i8bjCg"
}
Create a new expense itemization
POST /api/v3.0/expense/itemizations
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
content |
- | body |
Required The expense itemization object to create. |
Request URL
https://www.concursolutions.com/api/v3.0/expense/itemizations
JSON example of a successful response
{
"ID": "gWidFO7ikXV69FISvVWPbHe1Oj4FbCd0DCg",
"URI": "https://www.concursolutions.com/api/v3.0/expense/itemizations/gWidFO7ikXV69FISvVWPbHe1Oj4FbCd0DCg"
}
Update an expense itemization
DEPRECATED: 05/19/2016 UNSUPPORTED: 11/19/2016
PUT /api/v3.0/expense/itemizations/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required The ID of the expense itemization |
content |
- | body |
Required The partial or complete expense itemization object to update. |
Request URL
https://www.concursolutions.com/api/v3.0/expense/itemizations/gWidFO7ikXV6%24pcZsso2aBN0Aad4P5i8bjCg
JSON example of a successful response
no content
Delete an expense itemization
DEPRECATED: 05/19/2016 UNSUPPORTED: 11/19/2016
DELETE /api/v3.0/expense/itemizations/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required The ID of the expense itemization to delete. |
user |
string |
query |
Required The login ID of the user who owns the itemizations. The user must have the Web Services Admin role to use this parameter. |
Request URL
https://www.concursolutions.com/api/v3.0/expense/itemizations/gWidFO7ikXV6%24pcZsso2aBN0Aad4P5i8bjCg
JSON example of a successful response
no content
Schema
Itemizations
| Name | Type | Format | Description |
|---|---|---|---|
Items |
array |
Itemization | The result collection. |
NextPage |
string |
- | The URI of the next page of results, if any. |
Itemization
| Name | Type | Format | Description |
|---|---|---|---|
AllocationType |
string |
- | The type of allocation for the itemization. Possible values: P - partial allocation, F - full allocation, N - no allocation. Use the GET /expense/allocations function to get information about this entry's allocations. |
ApprovedAmount |
Decimal |
- | The approved amount of the expense itemization, in the report currency. |
Custom1 through Custom40 |
CustomField |
- | The details from the Custom fields. These fields may not have data, depending on the configuration. If the form field is configured as a List data type, the value will be the item code for this list. Use the GET /common/listitems operation to learn the item name. Maximum length: 64 characters |
Description |
string |
- | The description of the expense. Maximum length: 64 characters |
EntryID |
string |
- | Required The ID of the expense entry that is the parent for the itemization. Use the GET /expense/entries endpoint to learn the entry ID for the expense itemizations. |
ExpenseTypeCode |
string |
- | Required The code for the expense type. Use the GET /expense/expensegroupconfigurations endpoint to learn the expense type code for expense types that are active for this report's policy. |
ExpenseTypeName |
string |
- | Required The name of the expense type, localized to the user's language. |
HasComments |
Boolean |
- | Indicates whether the expense has comments. Use the GET ExpenseEntryComments endpoint to get information about this entry's comments. Format: true or false |
HasExceptions |
Boolean |
- | Indicates whether the expense has exceptions. Format: true or false |
ID |
string |
- | The unique identifier of the resource. |
IsBillable |
Boolean |
- | Indicates whether the itemization is billable. Format: true or false |
IsImageRequired |
Boolean |
- | Indicates whether a receipt image is required for the entry. Format: true or false |
IsPersonal |
Boolean |
- | Indicates whether the itemization is personal (that is, non-reimbursable). Format: true or false |
LastModified |
DateTime |
- | The UTC date when the itemization was last modified. |
LocationCountry |
string |
- | The country where the expense was incurred. Format: 2-letter ISO 3166-1 country code |
LocationID |
string |
- | The unique identifier for the location where the expense was incurred. Use the GET /common/locations function to get information for this location. |
LocationName |
string |
- | The location where the expense was incurred, usually the city name. |
LocationSubdivision |
string |
- | The state, province, or other country subdivision where the expense was incurred. Format: ISO 3166-2:2007 country subdivision |
OrgUnit1 through OrgUnit6 |
CustomField |
- | The details from the Org Unit fields. These fields may not have data, depending on the configuration. If the form field is configured as a List data type, the value will be the item code for this list. Use the GET /common/listitems operation to learn the item name. Maximum length: 64 characters |
PostedAmount |
Decimal |
- | The amount of the expense itemization, in the report currency. |
ReportID |
string |
- | Required The ID of the report that is the parent for the itemization. Use the GET /expense/reportdigests endpoint to learn the report ID for the itemizations. |
ReportOwnerID |
string |
- | Required The login ID for the report owner. Use the GET User Information endpoint to learn details about this user. |
SpendCategoryCode |
string |
- | Required The code for the spending category that is specified for this itemization. |
SpendCategoryName |
string |
- | Required The name of the spending category that is specified for this itemization, localized to the user's language. |
TransactionAmount |
Decimal |
- | The amount of the expense itemization, in the transaction currency of the parent expense entry. |
TransactionDate |
DateTime |
- | Required The date when the good or service associated with this itemization was provided. Format: YYYY-MM-DD |
URI |
string |
- | The URI to the resource. |
Custom Field
| Name | Type | Format | Description |
|---|---|---|---|
Code |
string |
- | For list fields, this is the list item code. |
ListItemID |
string |
- | For list fields, this is the list item ID. |
Type |
string |
- | The custom field type. Possible values: Amount, Boolean, ConnectedList, Date, Integer, List, Number, Text |
Value |
string |
- | The value in the Org Unit or Custom field. For list fields, this is the name of the list item. Maximum length: 48 characters |
Get report details
Retrieves the full set of information for the report. Includes the Report Header, Entry, Attendee, Itemization and Allocation details.
Some elements will appear only if the OAuth consumer has the Web Services Admin role. These include: The ReportKey element, the employee's credit card information, and the employee's bank account information, VAT information, Journal entries. Connectors that utilize this information go through a review process with SAP Concur that includes verification of secure data handling.
GET list of reports can be found here
Request
Request Parameters
Path Parameters
| Parameter | Required/Optional | Description |
|---|---|---|
| reportId | required | The identifier for the desired report. |
Example: https://us.api.concursolutions.com/api/expense/expensereport/v2.0/report/{reportId}
URI Source: The ReportId is returned in the ReportId element of the Get List of Reports function
Headers
Authorization Header
Authorization header with OAuth token for valid SAP Concur user. The OAuth consumer must have one of the following user roles in SAP Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard. These roles allow the user to manage data for the entire company.
Accept Header
application/xml
Response
Content Types
application/xml
Schema
This request will return a ReportDetails parent element.
ReportDetails
| Element | Description |
|---|---|
| UserLoginID | The user ID of the report owner. Maximum 128 characters. |
| EmployeeName | The name of the employee who created the report. Maximum 66 characters. |
| ReportID | The unique identifier for the report, which appears in the Concur Expense UI. Maximum 32 character varchar. |
| ReportKey | The unencrypted unique identifier for the report, that appears on the report header. The element appears only if the OAuth consumer has the Web Services Admin role in SAP Concur. Maximum 48 characters. |
| ReportName | The name of the report. Maximum 40 characters. |
| Purpose | The information from the Business Purpose field. |
| ReportDate | The date from the report header. Format: YYYY-MM-DDThh:mm:ss |
| CreationDate | The date the report was created. Format: YYYY-MM-DDThh:mm:ss |
| SubmitDate | The date the report was submitted. Maximum 10 characters. |
| PaidDate | The date the report was extracted for payment. This element has an attribute named i:nil. If the value for this element is null, the i:nil attribute will be set to true. Format: YYYY-MM-DDThh:mm:ss |
| CurrencyCode | The 3-letter ISO 4217 currency code for the expense report currency. The expense report currency is defined as the report creator's default reimbursement currency. |
| ReportTotal | The total amount of the report. Maximum 23 characters. |
| PersonalExpenses | The total amount of expenses marked as personal. Maximum 23 characters. |
| AmountDueEmployee | The total amount due to the employee for the report. Maximum 23 characters. |
| AmountDueCompanyCard | The total amount due to the company card for the report. Maximum 23 characters. |
| TotalClaimedAmount | The total amount of all non-personal expenses in the report. Maximum 23 characters. |
| TotalApprovedAmount | The total amount of approved expenses in the report. Maximum 23 characters. |
| ApprovalStatusCode | The approval status code for the report. |
| ApprovalStatusName | The approval status name for the report. |
| PaymentStatusCode | The unique identifier for the payment status of the report. |
| PaymentStatusName | The payment status of the report. |
| OrgUnit1 through OrgUnit6 | The details from the Org Unit custom fields. These may not have data, depending on configuration. Maximum 48 characters for each field. |
| Custom1 through Custom20 | The details from the Custom fields. These may not have data, depending on configuration. If report owner information is stored in these fields, it may be outdated. Refer to the ReportOwner parent element for the current owner information. Refer to the Custom Fields Child Elements table for more information. |
| LedgerName | The name of the expense report ledger. Maximum 20 characters. |
| PolicyID | The unique identifier of the policy that applies to this report. Maximum 64 characters. |
| EverSentBack | Whether the report has ever been sent back to the employee. Format: Y/N |
| HasException | Whether the report has exceptions. Format: Y/N |
| WorkflowActionURL | The URL to post a workflow action to the report using the Post Report Workflow Action function. |
| ExpenseEntriesList | This parent element has an ExpenseEntry child element for each entry. Refer to the ExpenseEntry elements table for more information. |
| ReportImageURL | The URL to access the image associated with the report. This URL is valid for 30 minutes after the web service call. |
| Country | The report country. Maximum 2 characters. Format: The ISO 3166-1 alpha-2 country code. Example: United States is US. |
| CountrySubdivision | The report country subdivision. Format: ISO 3166-2:2007 country subdivision. |
| ProcessingPaymentDate | The date that the report completed all approvals and was ready to be extracted for payment. Format: YYYY-MM-DD |
| ReceiptsReceived | If Y, then this report has its receipt receipt confirmed by the Expense Processor. Format: Y/N |
| ReportOwner | This parent element includes details about the employee who is the report owner. It saves the caller from calling the Get User Information function to get employee information commonly used in accounting integration. The ReportOwner element includes the most recent information about the report owner, at the time the report is requested. |
| EmployeeBankAccount | This parent element includes the bank account data found on the Bank Information page in Profile. This data is used in Payment System integrations where the payment system reimburses the employee via this bank account. |
ExpenseEntry
| Element | Description |
|---|---|
| ReportEntryID | The ID of the report entry. Maximum 13 characters. |
| ExpenseTypeID | The expense type ID for the expense entry. Expense Type IDs are returned in the ExpKey element by the Get Expense Group Configuration endpoint. |
| ExpenseTypeName | The expense type name. Maximum 64 characters. |
| SpendCategory | The spend category specified for this expense type. Varies by client, used in reporting. |
| PaymentTypeCode | The code for the payment type. Maximum 4 characters. |
| PaymentTypeName | The name for the payment type. Maximum 80 characters. |
| TransactionDate | The date of the expense entry. Maximum 10 characters. Format: YYYY-MM-DD |
| TransactionCurrencyName | The name of the transaction currency. Example: US, Dollar |
| ExchangeRate | The exchange rate that applies to the entry. Maximum 23 characters. |
| TransactionAmount | The amount of the expense entry in the original transaction currency. Maximum 23 characters. |
| PostedAmount | The amount of the expense entry in the user's reimbursement currency. The user's reimbursement currency is returned in the CrnCode element for the report. Maximum 23 characters. |
| ApprovedAmount | The approved amount of the expense entry in the user's reimbursement currency.The user's reimbursement currency is returned in the CrnCode element for the report. Maximum 23 characters. |
| BusinessPurpose | The text from the Business Purpose field of the entry. Maximum 64 characters. |
| VendorDescription | The vendor name of the expense entry, which can be entered manually by the user or imported from the card transaction Merchant Name field. Maximum 64 characters. |
| LocationName | The location for the expense entry, usually the city name. |
| LocationSubdivision | The location's State, Province, or Country Subdivision. Maximum 6 characters. |
| LocationCountry | The location's Country. Maximum 2 characters. |
| OrgUnit1 through OrgUnit6 | The details from the Org Unit custom fields. These may not have data, depending on configuration. Maximum 48 characters for each field. |
| Custom1 through Custom40 | The details from the Custom fields. These may not have data, depending on configuration. Refer to the Custom Fields elements table for more information. |
| FormID | The ID for the expense entry form. |
| EntryImageID | The unique identifier for the image associated with the entry. |
| HasVat | Whether the entry contains VAT data. Maximum 1 character. Format: Y/N |
| HasComments | Whether the expense entry has comments. Maximum 1 character. Format: Y/N |
| CommentCount | The number of comments associated with the expense entry. |
| IsItemized | Whether the expense entry is itemized. Maximum 1 character. Format: Y/N |
| HasExceptions | Whether the expense entry has exceptions. Maximum 1 character. Format: Y/N |
| IsPersonal | Whether the expense entry is marked as personal. Maximum 1 character. Format: Y/N |
| HasAttendees | Whether the expense entry has attendees. Maximum 1 character. Format: Y/N |
| HasAllocation | Defines the amount of allocations for the expense. Maximum 1 character. Possible values are: P, for partial allocation, F, for full allocation, or N, for no allocation. |
| IsCreditCardCharge | Whether the expense came from a credit card feed. Maximum 1 character. Format: Y/N |
| IsPersonalCardCharge | Whether the expense came from a personal card feed. Maximum 1 character. Format: Y/N |
| ReceiptRequired | Whether the original receipt is required for the entry. Maximum 1 character. Format: Y/N |
| ImageRequired | Whether a receipt image is required for the entry. Maximum 1 character. Format: Y/N |
| E-ReceiptID | The ID for the attached e-receipt, if available. |
| LastModifiedDate | The date the expense entry was last changed. Maximum 19 characters. Format: YYYY-MM-DDThh:mm:ss |
| ItemizationsList | The list of itemizations for the expense entry. This parent element will have at least one Itemization child element. If the expense entry is not itemized, the Itemization will contain the same values as the entry. If the expense entry has itemizations, there will be one Itemization child element for each itemization. Refer to the Itemization elements table for more information. NOTE: There are a few rare cases where the ItemizationsList will be null. This happens when a report entry has a payment type code that is not IBCP with offsets or CBCP and there is a Regular or Child expense entry with an Approved Amount equal to zero. The expense entry will have a Null ItemizationsList. |
| ReportEntryVendorName | Vendor name the employee selected from the Vendor list field. Maximum 64 characters. |
| ReportEntryReceiptReceived | If Y, then this entry has been marked as reviewed by a processor. Maximum 1 character. Format: Y/N |
| ReportEntryReceiptType | Maximum 1 character. One of these: T = tax receipt R= regular receipt N = no receipt |
| CardTransaction | This parent element includes the card transaction data found in the card transaction associated to this expense entry. This data is used in Payment System integrations where the payment system reimburses the card issuer for the indicated card account. Refer to the CardTransaction elements table. |
| ExpensePay | Whether the entry was paid using the Expense Pay service. This element has a value if the report has reached the Processing Payment workflow step. Format: Yes/No |
Itemization
| Element | Description |
|---|---|
| ItemType | The type of itemization. If the expense entry does not have any itemizations, this will be set to Regular. If the expense entry contains itemizations, each one will be set to Child. |
| ItemizationID | The unique identifier for the itemization. Maximum 19 characters. |
| ExpenseTypeID | The expense type ID for the itemization. |
| ExpenseTypeName | The expense type for the itemization. Maximum 64 characters. |
| TransactionDate | The date of the transaction. Maximum 10 characters. Format: YYYY-MM-DD |
| TransactionAmount | The amount for the itemization in the expense currency. Maximum 23 characters. |
| PostedAmount | The amount for the itemization in the user's reimbursement currency. The user's reimbursement currency is returned in the CrnCode element for the report. Maximum 23 characters. |
| ApprovedAmount | The approved amount of the itemization in the user's reimbursement currency. The user's reimbursement currency is returned in the CrnCode element for the report. Maximum 23 characters. |
| BusinessPurpose | The business purpose field from the report header. |
| OrgUnit1 through OrgUnit6 | The details from the Org Unit custom fields. These may not have data, depending on configuration. Maximum 48 characters for each field. |
| Custom1 through Custom40 | The custom fields associated with the itemization. These may not have data, depending on your configuration. Refer to the Custom Fields elements table for more information. |
| Value | The value in the custom field. Maximum 48 characters. |
| Code | Custom list fields will include the list item code in this element. |
| HasComments | Whether the itemization has comments. Maximum 1 character. Format: Y/N |
| CommentCount | The number of comments associated with the itemization. |
| IsPersonal | Whether the itemization is personal. Maximum 1 character. Format: Y/N |
| LastModified | The UTC date when the itemization was last modified. Maximum 19 characters. Format: YYYY-MM-DDThh:mm:ss |
| AttendeesList | This parent element contains one Attendee element for each associated attendee. Refer to the Attendee elements table for more information. |
| AllocationsList | This parent element contains at least one Allocation element. It will contain multiple Allocation elements if there are multiple allocations for the itemization. Refer to the Allocation elements table. |
Attendee
| Element | Description |
|---|---|
| AttendeeType | The type of attendee. Maximum 40 characters. |
| FirstName | The attendee's first name. Maximum 50 characters. |
| LastName | The attendee's last name. Maximum 132 characters. |
| Company | The attendee's company name. Maximum 150 characters. |
| Title | The attendee's title. Maximum 32 characters. |
| ExternalID | The unique identifier for the attendee, managed outside SAP Concur. Maximum 48 characters. |
| Custom1 through Custom20 | The details from the custom fields. These may not have data, depending on configuration. Refer to the Custom Fields elements table for more information. |
| HasExceptionsPrevYear | Whether the attendee has exceptions in the previous year, based on yearly total limits for attendees. Maximum 1 character. Format: Y/N |
| HasExceptionsYTD | Whether the attendee has exceptions in the current year, based on yearly total limits for attendees. Maximum 1 character. Format: Y/N |
| IsDeleted | Whether the attendee is marked as deleted. Maximum 1 character. Format: Y/N |
| OwnerName | The name of the employee that owns the attendee record. |
| TotalAmountPrevYear | The total amount spent on the attendee in the previous calendar year. |
| TotalAmountYTD | The total amount spent on the attendee in the current calendar year. |
| VersionNumber | The attendee's version number. |
| AttendeeID | Attendee unique identifier within SAP Concur. |
| AttendeeTypeCode | The unique identifier for the attendee type. |
| AttendeeOwnerID | The unique identifier for the person or system that owns the attendee. |
| CurrencyCode | The 3-letter ISO 4217 currency code for attendee related amounts. |
Allocation
| Element | Description |
|---|---|
| AllocationID | The unique alphanumeric identifier for the allocation. Maximum 13 characters. |
| Percentage | The percentage of the expense that is included in this allocation. Maximum 11 characters. |
| AccountCode1 | The primary accounting code assigned to the expense type associated with this allocation. Typically, expense types have only this primary account code. |
| AccountCode2 | The secondary or alternative accounting code assigned to the expense type associated with this allocation. In rare cases some expense types include this accounting code to handle special cases. One example of these special cases is when using travel allowance, where one expense would use the primary account code for the allowed amount, and the alternative account code for the overage. Another example is personal use of a company car. Refer to the Expense: Account Codes Setup Guide for more information on how Concur Expense determines which accounting codes to use. |
| Custom1 through Custom20 | The custom fields associated with the allocation. These may not have data, depending on your configuration. Refer to the Custom Fields elements table for more information. |
| JournalEntriesList | This parent element contains at least one JournalEntry child element. It contains multiple JournalEntry elements if the allocation has multiple journal entries. Refer to the JournalEntry elements table for more information. |
| VATDataList | This parent element contains one VATData element for each VAT line item. This element will be empty if there are no VAT line items. Refer to the VATData elements table for more information. |
JournalEntry
| Element | Description |
|---|---|
| JournalID | Unique identifier for the journal entry. |
| PayerPaymentTypeName | Payer payment type. Maximum 64 characters. One of these: Company = Company Employee = Employee Payment Type for the Credit Card Payment Type |
| PayerPaymentTypeCode | Payment code name for the payer. Maximum 80 characters. |
| PayeePaymentTypeName | Payee payment type. Maximum 64 characters. One of these: Company = Company Employee = Employee Payment Type for the Credit Card Payment Type |
| PayeePaymentCode | Payment code name for the payee. Maximum 80 characters. |
| AccountCode | The account code Concur Expense determines should apply to this journal entry. For journal entries associated to an allocation, Concur Expense uses the business logic described in the Expense: Account Codes Setup Guide to determine whether the primary or secondary account code should apply. When there is no allocation associated to the journal entry, Concur Expense uses clearing account codes for Credit Card and Cash Advance for personal use of a company paid expense or a cash advance issued to an employee respectively. Maximum 48 characters. NOTE: The developer should almost always use this accounting code when creating financial transactions in financial systems. In some situations a developer may need to use the accounting codes in the Allocation parent element. |
| DebitOrCredit | Maximum 2 characters. Either: DR = Debit CR = Credit |
| Amount | Value, as credit or debit, of the amount to be exchanged between the payer and payee for this expense account code (not an absolute value) Maximum 23 characters. EXAMPLES: Value of zero, credit, or debit, as the following: 0 (Zero) "0" + (Plus / Debit) "+50.00" - (Minus / Credit) "-50.00" |
| JobRunKey | Either the unique identifier for job run for the accounting extract that processed this journal, or a static value indicating the journal was processed by Manual Pay, Expense Pay, or some other system. |
VATData
| Element | Description |
|---|---|
| TaxName | Tax authority name. Maximum 50 characters. |
| TaxAuthorityLabel | 5-digit code that appears on the expense entry pages. Maximum 5 characters. |
| TaxTransactionAmount | Calculated tax amount for this expense in the spend currency. Maximum 23 characters. |
| TaxPostedAmount | Calculated tax amount for this expense entry in the reimbursement currency. Maximum 23 characters. |
| Source | Specifies how the tax data was derived. Maximum 4 characters. One of these: CARD = Provided from company card USER = Entered by employee SYST = Calculated by system PROC = Entered by processor |
| TaxReclaimTransactionAmount | Calculated amount of tax eligible for reclaim in the spend currency. Maximum 23 characters. |
| TaxReclaimPostedAmount | Calculated amount of tax eligible for reclaim in the reimbursement currency. Maximum 23 characters. |
CardTransaction
| Element | Description |
|---|---|
| AccountNumber | Credit card number used for this expense. This value is encrypted in the response. Maximum 255 characters. |
| CardDescription | The name on the credit card used for this expense. Maximum 255 characters. |
| CardTypeCode | Type of credit card. |
| TransactionReferenceNumber | Reference number from the credit card vendor. Maximum 64 characters. |
| TransactionCCTType | Transaction type supplied by card vendor. Maximum 3 characters. One of these: ANF = Annual Fees CAV = Cash Advance CCF = Cash and Check Fees CHG = Other Bank Charges and Fees FNC = Finance Charges LAF = Late Fees NSF = Insufficient Funds Check Fees PAY = Payment RPE = Credit Card Transaction |
| TransactionID | Calculated value assigned to this card entry during the import process. Maximum 32 characters. |
| TransactionAmount | Amount of the charge in the spend currency. Maximum 23 characters. |
| TaxAmount | Amount of tax on the transaction amount (if provided by card vendor). Maximum 23 characters. |
| TransactionAlphaCode | Currency code for the spend currency. Maximum 3 characters. Format: ISO 4217 3 digit alpha code |
| PostedAmount | Amount of the charge in the billing currency of the card. Maximum 23 characters. |
| PostedAlphaCode | Currency code for the card billing currency. Maximum 3 characters. Format: ISO 4217 3 digit alpha code |
| TransactionDate | Date the charge was made at the merchant. Maximum 10 characters. |
| PostedDate | Date the charge was posted to the credit card account. Maximum 10 characters. |
| Description | Description of the charge from the merchant. Maximum 42 characters. |
| MasterCardCode | Merchant code sent from the credit card vendor. Maximum 5 characters. |
| TransactionMerchantName | Name of the merchant. Maximum 50 characters. |
| MerchantCity | Merchant city. Maximum 40 characters. |
| MerchantState | Merchant State/Province. Maximum 32 characters. |
| MerchantCountryCode | Merchant country location code. Format: 2 digit alpha code |
| MerchantReferenceNumber | Merchant reference number passed from the merchant to the card. Maximum 15 characters. |
| ExchangeRateFromBillingToEmployeeCurrency | Currency exchange rate used between the credit card billing currency and the employee's reimbursement currency. Maximum 23 characters. |
| BillingAmount | Amount due to the company card from the employee or company (depending on who is responsible for the bill) for this detail row. Maximum 23 characters. |
| AccountNumberLastSegment | The last 4 digits of the Card Account. |
Custom Fields
| Element | Description |
|---|---|
| Type | The custom field type. Will be one of the following: Amount, Boolean, ConnectedList, Date, Integer, List, Number, Text |
| Value | The value in the custom field. Maximum 48 characters. |
| Code | Custom list fields will include the list item code in this element. |
ReportOwner
| Element | Description |
|---|---|
| EmployeeCustom21 | The report owner's group ID. Maximum 48 characters. |
| EmployeeID | Employee ID often also serves as the employee's Vendor ID for AP system integrations or Payroll ID for Payroll integrations. Maximum 48 characters. |
| EmployeeOrgUnit1 through EmployeeOrgUnit6 | The report owner's organizational unit information. Maximum 48 characters for each field. |
| FirstName | The report owner's first name. Maximum 32 characters. |
| LastName | The report owner's last name. Maximum 32 characters. |
| MiddleInitial | The report owner's middle initial. Maximum 1 character. |
| ReimbursementMethodCode | The report owner's reimbursement method code, as defined in the employee's Profile. |
EmployeeBankAccount
| Element | Description |
|---|---|
| BankNumber | The bank identification number entered on the Bank Information page. Maximum 11 characters. |
| BankName | The bank name entered on the Bank Information page. Maximum 48 characters. |
| BranchLocation | The branch location entered on the Bank Information page. Maximum 30 characters. |
| AccountNumber | The bank account number entered on the Bank Information page. Maximum 100 characters. |
| AccountName | The name on the account entered on the Bank Information page. |
| PostalAddressLine1 | The postal address line 1 entered on the Bank Information page. Maximum 48 characters. |
| PostalAddressLine2 | The postal address line 2 entered on the Bank Information page. Maximum 48 characters. |
| PostalAddressCity | The postal address city entered on the Bank Information page. Maximum 24 characters. |
| PostalAddressRegion | The postal address region entered on the Bank Information page. Maximum 24 characters. |
| PostalAddressCode | The postal address code entered on the Bank Information page. Maximum 20 characters. |
| PostalAddressCountry | The postal address country entered on the Bank Information page. Maximum 2 characters. Format: The ISO 3166-1 alpha-2 country code. Example: United States is US. |
Examples
XML Example Request
GET https://us.api.concursolutions.com/api/expense/expensereport/v2.0/report/n6ujbuLd1Arwe45lT7As3ThJYJf2dAsrrEW HTTP/1.1
Authorization: OAuth {access token}
...
XML Example of Successful Response
HTTP/1.1 200 OK
Content-Type: application/xml
<?xml version="1.0" encoding="utf-8"?>
<ReportDetails xmlns="http://us.api.concursolutions.com/api/expense/expensereport/2012/07" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<UserLoginID>cm@example.com</UserLoginID>
<EmployeeName>Miller, Chris</EmployeeName>
<ReportID>425FE2ADB4954FCA90CD</ReportID>
<ReportName>Client Meeting</ReportName>
<Purpose>Sales meeting</Purpose>
<ReportDate>2013-01-10T00:00:00</ReportDate>
<CreationDate>2013-01-11T01:58:20</CreationDate>
<SubmitDate>0001-01-01T00:00:00</SubmitDate>
<PaidDate i:nil="true" />
<CurrencyCode>USD</CurrencyCode>
<ReportTotal>50.00000000</ReportTotal>
<PersonalExpenses>0.00000000</PersonalExpenses>
<AmountDueEmployee>50.00000000</AmountDueEmployee>
<AmountDueCompanyCard>0.00000000</AmountDueCompanyCard>
<TotalClaimedAmount>50.00000000</TotalClaimedAmount>
<TotalApprovedAmount>50.00000000</TotalApprovedAmount>
<ApprovalStatusCode>A_NOTF</ApprovalStatusCode>
<ApprovalStatusName>Not Submitted</ApprovalStatusName>
<PaymentStatusCode>P_NOTP</PaymentStatusCode>
<PaymentStatusName>Not Paid</PaymentStatusName>
<OrgUnit1>Sales</OrgUnit1>
<OrgUnit2 />
<OrgUnit3 />
<OrgUnit4 />
<OrgUnit5 />
<OrgUnit6 />
<Custom1 />
<Custom2 />
<Custom3 />
<Custom4 />
<Custom5 />
<Custom6 />
<Custom7 />
<Custom8 />
<Custom9 />
<Custom10 />
<Custom11 />
<Custom12 />
<Custom13 />
<Custom14 />
<Custom15 />
<Custom16 />
<Custom17 />
<Custom18 />
<Custom19 />
<Custom20 />
<LedgerName>Corporate</LedgerName>
<PolicyID>ndrF8hjzl9FtFUdfaBwVvXP$sD1vDpRKNf</PolicyID>
<EverSentBack>N</EverSentBack>
<HasException>N</HasException>
<WorkflowActionURL />
<ExpenseEntriesList>
<ExpenseEntry>
<ReportEntryID>nE0avYnILN9mHdTErNSd2pH45udFoNQ$po</ReportEntryID>
<ExpenseTypeID>BUSML</ExpenseTypeID>
<ExpenseTypeName>Business Meal (attendees)</ExpenseTypeName>
<SpendCategory>Entertainment</SpendCategory>
<PaymentTypeCode>CASH</PaymentTypeCode>
<PaymentTypeName>Cash</PaymentTypeName>
<TransactionDate>2013-01-10T00:00:00</TransactionDate>
<TransactionCurrencyName>US, Dollar</TransactionCurrencyName>
<ExchangeRate>1.00000000000000</ExchangeRate>
<TransactionAmount>50.00000000</TransactionAmount>
<PostedAmount>50.00000000</PostedAmount>
<ApprovedAmount />
<BusinessPurpose />
<VendorDescription />
<LocationName>Washington</LocationName>
<LocationSubdivision>US-DC</LocationSubdivision>
<LocationCountry>US</LocationCountry>
<OrgUnit1>Sales</OrgUnit1>
<OrgUnit2 />
<OrgUnit3 />
<OrgUnit4 />
<OrgUnit5 />
<OrgUnit6 />
<Custom1 />
<Custom2 />
<Custom3 />
<Custom4 />
<Custom5 />
<Custom6 />
<Custom7 />
<Custom8 />
<Custom9 />
<Custom10 />
<Custom11 />
<Custom12 />
<Custom13 />
<Custom14 />
<Custom15 />
<Custom16 />
<Custom17 />
<Custom18 />
<Custom19 />
<Custom20 />
<Custom21 />
<Custom22 />
<Custom23 />
<Custom24 />
<Custom25 />
<Custom26 />
<Custom27 />
<Custom28 />
<Custom29 />
<Custom30 />
<Custom31 />
<Custom32 />
<Custom33 />
<Custom34 />
<Custom35 />
<Custom36 />
<Custom37 />
<Custom38 />
<Custom39 />
<Custom40 />
<FormID>nAaT8$puKKOhs7h2wespCW7vyyxJAJcyb5</FormID>
<EntryImageID />
<HasVat>N</HasVat>
<HasComments>N</HasComments>
<CommentCount>0</CommentCount>
<IsItemized>Y</IsItemized>
<HasExceptions>N</HasExceptions>
<IsPersonal>N</IsPersonal>
<HasAttendees>Y</HasAttendees>
<HasAllocation>N</HasAllocation>
<IsCreditCardCharge>N</IsCreditCardCharge>
<IsPersonalCardCharge>N</IsPersonalCardCharge>
<ReceiptRequired>N</ReceiptRequired>
<ImageRequired>N</ImageRequired>
<E-ReceiptID />
<LastModified>2013-01-11T01:59:52</LastModified>
<ItemizationsList>
<Itemization>
<ItemType>Regular</ItemType>
<ItemizationID>nE0avYnILN9mHdTErNSd2pH45udFoNQ$po</ItemizationID>
<ExpenseTypeID>BUSML</ExpenseTypeID>
<ExpenseTypeName>Business Meal (attendees)</ExpenseTypeName>
<TransactionDate>2013-01-10T00:00:00</TransactionDate>
<TransactionAmount>50.00000000</TransactionAmount>
<PostedAmount>50.00000000</PostedAmount>
<ApprovedAmount />
<BusinessPurpose />
<OrgUnit1>Sales</OrgUnit1>
<OrgUnit2 />
<OrgUnit3 />
<OrgUnit4 />
<OrgUnit5 />
<OrgUnit6 />
<Custom1 />
<Custom2 />
<Custom3 />
<Custom4 />
<Custom5 />
<Custom6 />
<Custom7 />
<Custom8 />
<Custom9 />
<Custom10 />
<Custom11 />
<Custom12 />
<Custom13 />
<Custom14 />
<Custom15 />
<Custom16 />
<Custom17 />
<Custom18 />
<Custom19 />
<Custom20 />
<Custom21 />
<Custom22 />
<Custom23 />
<Custom24 />
<Custom25 />
<Custom26 />
<Custom27 />
<Custom28 />
<Custom29 />
<Custom30 />
<Custom31 />
<Custom32 />
<Custom33 />
<Custom34 />
<Custom35 />
<Custom36 />
<Custom37 />
<Custom38 />
<Custom39 />
<Custom40 />
<HasComments>N</HasComments>
<CommentCount>0</CommentCount>
<IsPersonal>N</IsPersonal>
<LastModified>2013-01-11T01:59:52</LastModified>
<AllocationsList />
<AttendeesList>
<Attendee>
<AttendeeType>BUSGUEST</AttendeeType>
<FirstName>Pat</FirstName>
<LastName>Davis</LastName>
<Company />
<Title />
<ExternalID />
<Custom1 />
<Custom2 />
<Custom3 />
<Custom4 />
<Custom5 />
<Custom6 />
<Custom7 />
<Custom8 />
<Custom9 />
<Custom10 />
<Custom11 />
<Custom12 />
<Custom13 />
<Custom14 />
<Custom15 />
<Custom16 />
<Custom17 />
<Custom18 />
<Custom19 />
<Custom20 />
<HasExceptionsPrevYear>N</HasExceptionsPrevYear>
<HasExceptionsYTD>N</HasExceptionsYTD>
<IsDeleted>N</IsDeleted>
<OwnerEmpName>Miller, Chris</OwnerEmpName>
<TotalAmountPrevYear>0.00000000</TotalAmountPrevYear>
<TotalAmountYTD>0.00000000</TotalAmountYTD>
<VersionNumber>1</VersionNumber>
<AttendeeID>nFaAj038Hw$plfUD8be0I45wTx8$sMlTd$pP</AttendeeID>
<AttendeeTypeCode>BUSGUEST</AttendeeTypeCode>
<AttendeeOwnerID>cm@example.com</AttendeeOwnerID>
<CurrencyCode>USD</CurrencyCode>
</Attendee>
</AttendeesList>
</Itemization>
<Itemization>
<ItemType>Child</ItemType>
<ItemizationID>nE0avYnILN9g$s6lCFX0jFBWmHAiTYYf9C</ItemizationID>
<ExpenseTypeID>BRKFT</ExpenseTypeID>
<ExpenseTypeName>Breakfast</ExpenseTypeName>
<TransactionDate>2013-01-10T00:00:00</TransactionDate>
<TransactionAmount>50.00000000</TransactionAmount>
<PostedAmount>50.00000000</PostedAmount>
<ApprovedAmount>50.00000000</ApprovedAmount>
<BusinessPurpose />
<OrgUnit1>Sales</OrgUnit1>
<OrgUnit2 />
<OrgUnit3 />
<OrgUnit4 />
<OrgUnit5 />
<OrgUnit6 />
<Custom1 />
<Custom2 />
<Custom3 />
<Custom4 />
<Custom5 />
<Custom6 />
<Custom7 />
<Custom8 />
<Custom9 />
<Custom10 />
<Custom11 />
<Custom12 />
<Custom13 />
<Custom14 />
<Custom15 />
<Custom16 />
<Custom17 />
<Custom18 />
<Custom19 />
<Custom20 />
<Custom21 />
<Custom22 />
<Custom23 />
<Custom24 />
<Custom25 />
<Custom26 />
<Custom27 />
<Custom28 />
<Custom29 />
<Custom30 />
<Custom31 />
<Custom32 />
<Custom33 />
<Custom34 />
<Custom35 />
<Custom36 />
<Custom37 />
<Custom38 />
<Custom39 />
<Custom40 />
<HasComments>N</HasComments>
<CommentCount>0</CommentCount>
<IsPersonal>N</IsPersonal>
<LastModified>2013-01-11T01:59:52</LastModified>
<AllocationsList>
<Allocation>
<AllocationID>ngYn5SB4OUXgRV6P8VgsQQr88SaKYvbqz</AllocationID>
<Percentage>100.00000000%</Percentage>
<AccountCode1>AC_BRKFT1</AccountCode1>
<AccountCode2>AC_BRKFT2</AccountCode2>
<Custom1 />
<Custom2 />
<Custom3 />
<Custom4 />
<Custom5 />
<Custom6 />
<Custom7 />
<Custom8 />
<Custom9 />
<Custom10 />
<Custom11 />
<Custom12 />
<Custom13 />
<Custom14 />
<Custom15 />
<Custom16 />
<Custom17 />
<Custom18 />
<Custom19 />
<Custom20 />
<VATDataList />
</Allocation>
</AllocationsList>
<AttendeesList />
</Itemization>
</ItemizationsList>
<UserLoginID>cm@example.com</UserLoginID>
</ExpenseEntry>
</ExpenseEntriesList>
<Country>US</Country>
<CountrySubdivision></CountrySubdivision>
<ProcessingPaymentDate></ProcessingPaymentDate>
<ReceiptsReceived>Y</ReceiptsReceived>
<ReportOwner>
<EmployeeID>cm@example.com</EmployeeID>
<LastName>Chris</LastName>
<FirstName>Miller</FirstName>
<MiddleInitial></MiddleInitial>
<EmployeeCustom21></EmployeeCustom21>
<EmployeeOrgUnit1></EmployeeOrgUnit1>
<EmployeeOrgUnit2></EmployeeOrgUnit2>
<EmployeeOrgUnit3></EmployeeOrgUnit3>
<EmployeeOrgUnit4></EmployeeOrgUnit4>
<EmployeeOrgUnit5></EmployeeOrgUnit5>
<EmployeeOrgUnit6></EmployeeOrgUnit6>
<ReimbursementMethodCode>CNQRPAY</ReimbursementMethodCode>
</ReportOwner>
</ReportDetails>
Integration Status
The integration status of the supplied object. Currently supports expense reports.
This resource allows developers to ensure that the necessary transactions to account for expenses and arrange payment for the expenses in a specified report were created in the financial system prior to committing the expense report in Concur Expense. If they were, the developer uses this function to indicate the report was successfully integrated and move the report forward in the workflow to the Paid step. In Concur Expense, when a report arrives at the Paid workflow step the report is committed, meaning its data can't be changed and it can't be sent back in the workflow.
URI
https://www.concursolutions.com/api/expense/expensereport/v2.0/integrationstatus/
Operations
Request
Request Parameters
Path Parameters
| Parameter | Required/Optional | Description |
|---|---|---|
| report/{ReportID} | required | The report keyword and the ReportID for the report that has been successfully integrated into the financial system. The ReportID is returned in the ReportID element by the Get List of Reports and the Get Report Details responses. |
Headers
Authorization Header
Authorization header with OAuth token for valid SAP Concur user. Required. The OAuth consumer must have the following user role: Web Services Administrator
Content-Type Header
- application/json
- application/xml
Response
Content Types
- application/xml
- application/json
Schema
The response will include an ActionStatus parent element (XML), or an object (JSON) with the following child elements (XML) or name/value pairs (JSON).
ActionStatus elements
| Element | Description |
|---|---|
| Status | Whether the request was successful. Possible values: SUCCESS, FAILURE. |
| Message | Provides further details for errors. |
Examples
XML Example Request
POST https://www.concursolutions.com/api/expense/expensereport/v2.0/integrationstatus/report/nx2WRNzp18$wjehk%wqEL6EDHRwi9r$paQS1UqyL6a454QitqQ HTTP/1.1
Authorization: OAuth {access token}
Accept: application/xml
...
XML Example of Successful Response
HTTP/1.1 200 OK
Content-Type: application/xml
<ActionStatus xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Message>SUCCESS</Message>
<Status>SUCCESS</Status>
</ActionStatus>
JSON Example of Successful Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"Status": "SUCCESS",
"Message": "SUCCESS"
}
JSON Example of Response with Error
HTTP/1.1 200 OK
Content-Type: application/json
{
"Status": "FAILURE",
"Message": "To use the POST Expense Journal Entry Job Key the report must be at the Processing Payment or Payment Confirmed Payment Status."
}
Create an exception to a report
Posts an exception to the report, and associates it with one of the following data levels: Report Header, Entry, Itemization, Allocation. This endpoint requires familiarity with the company's exception code configuration.
Request
Request Parameters
Path Parameters
| Parameter | Required/Optional | Description |
|---|---|---|
| {reportKey}/Exceptions | required | The identifier for the desired report and the exceptions keyword. |
Example: https://www.concursolutions.com/api/expense/expensereport/v1.1/report/{reportKey}/Exceptions
URI Source: The reportKey value is returned in the RptKey element by the Get Report Details response.
Headers
Authorization Header
Authorization header with OAuth token for valid SAP Concur user. Required.
Content-Type Header
application/xml
Request Schema
This request should contain an Exceptions parent element with an Exception parent element for each exception included in the report. The Exception element contains the following child elements:
Exception Elements
| Element | Required (must contain value)? | Description |
|---|---|---|
| Index | Y | The exception's location in a batch of exceptions. Should start at 1 and increment sequentially. This value is used to identify the record if there is an error. |
| ObjectType | Y | The type of object to assign the exception. Format: Report, Entry, or Allocation. When sending a Report level exception, the ObjectType and ObjectId can be null, as the report key is supplied in the URI. |
| ObjectId | Y | The unique identifier for the object to associate with the exception. Returned by the Get Report Details function. Must be the value from one of the following fields: Entry or Itemization: Use the RpeKey. Allocation: Use AllocationKey. Report Header: Null value. When sending a Report level exception, the ObjectType and ObjectId can be null, as the report key is supplied in the URI. |
| ExceptionCode | Y | The Exception Code for the exception to assign to the object. Must be a configured exception code in Expense. Example: NODATE |
Response
Content Types
application/xml
Response Schema
This request will return an exception-result parent element.
Exception-Result Elements
| Element | Description |
|---|---|
| exceptions-succeeded | The number of exceptions processed that were successfully assigned. |
| exceptions-failed | The number of exceptions processed that were not successfully added. |
| errors | This will contain an error parent element for each record failure. The error element will contain the following child elements: Index: The exception's location in the batch. message: The error message. |
| ExceptionDetails | This parent element will contain an ExceptionInfo parent element for all exceptions that did not cause an error, and will contain the following child elements: Index: The exception's location in the batch. Status: The status of the request. |
Examples
XML Example Request
POST https://www.concursolutions.com/api/expense/expensereport/v1.1/report/3FK118eIJ844Uwl0HF32/Exceptions HTTP/1.1
Authorization: OAuth {access token}
Content-Type: application/xml
<Exceptions xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Exception>
<Index>1</Index>
<ObjectType>Report</ObjectType>
<ObjectId>nxxKgLlnRODp$sie8Hq1UviOJ2AbpS7dCP</ObjectId>
<ExceptionCode>APPRVTO</ExceptionCode>
</Exception>
<Exception>
<Index>2</Index>
<ObjectType>Entry</ObjectType>
<ObjectId>nxxKgLlnRODp$sie8Hq1UviOJ2deAbpS7dC0</ObjectId>
<ExceptionCode>APPRVTO</ExceptionCode>
</Exception>
</Exceptions>
XML Example of Response With Success and Failure
<exception-result xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<exceptions-succeeded>1</exceptions-succeeded>
<exceptions-failed>1</exceptions-failed>
<errors>
<error>
<Index>2</Index>
<message>Invalid Exception Code</message>
</error>
</errors>
<ExceptionDetails>
<ExceptionInfo>
<Index>1</Index>
<Status>Success</Status>
</ExceptionInfo>
</ExceptionDetails>
</exception-result>
Submit an expense report
Triggers the Submit workflow action for the specified report.
Important Note: This endpoint submits the expense report as if the original report owner had submitted it. Consult your company's Expense administrator to confirm that the web service should be allowed to submit reports on behalf of users. If you wish to enforce the expense report delegate functionality, use the Get Expense Delegators function to determine if the user in question has the correct permissions to submit on behalf of the report owner.
Request
Request Parameters
Path Parameters
| Parameter | Required/Optional | Description |
|---|---|---|
| {reportKEY}/submit | required | The identifier for the desired report and the submit keyword. |
Example: https://www.concursolutions.com/api/expense/expensereport/v1.1/report/{reportKEY}/submit
URI Source: The reportId value is returned by the Get List of Reports and Get Report Details functions, and as part of the Report-Details-Url element of the Post Expense Report Header function.
Content Types
application/xml
Authorization Header
Authorization: This request requires an Authorization header with an OAuth token for a valid SAP Concur user.
X_UserID: This request requires an additional field in the authorization header, identifying the report owner. This identifier is the SAP Concur login for the user, and is often also the email address of the user. The field format is:
X_UserID: expenseuser@example.com
Response
Schema
This request will return a ReportStatus parent element with the following child elements.
Report Status Elements
| Element | Description |
|---|---|
| Message | The error message. Only appears if a submission error was generated. |
| Status | The status of the report submit action. |
If the report submission triggered an exception, a ReportExceptions parent element will be provided, with a ReportException parent element for each exception. The ReportException element contains the following elements.
Report Exception Schema
| Element | Description |
|---|---|
| CrnCode | The currency code of the entry. |
| EventCode | The event that resulted in the exception. |
| ExceptionCode | The company-defined exception code. |
| ExceptionErrorCode | The severity of the exception. Exceptions with ERROR as the code cannot be submitted. |
| ExceptionVisibility | Which users are able to see the exception. |
| ExpKey | The expense type key for the entry. |
| ExpName | The expense type name for the entry. |
| IsCleared | Whether the exception has been cleared by the Expense Processor. |
| SeverityLevel | A numeric value indicating the severity level of the exception. The value threshold is configurable. |
| TransactionAmount | The amount of the entry. |
| TransactionDate | The date of the entry. |
| Type | The exception type. |
Examples
XML Example Request
POST https://www.concursolutions.com/api/expense/expensereport/v1.1/report/nxxKgLlnROz$sQ6SKJFjLNs4OWBErcJ8yX/submit HTTP/1.1
Authorization: OAuth {access token}
X-UserID: cmiller@example.com
...
XML example of Successful Response
<ReportStatus xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Status>SUCCESS</Status>
</ReportStatus>
Post an expense report workflow action
Posts a workflow action for the supplied expense report. The workflow action moves the expense report through the workflow process.
Workflow Actions
The available actions are:
- Approve: The report successfully completes the current workflow step. The report will continue in the workflow, and may require additional approvals based on configuration. If the report was in the Processing Payment status, it will be moved to the Paid status.
NOTES:- Reports can't be moved from Processing Payment to Paid until all of their expense entries have been extracted or manually paid. Wait until the extract process completes for the report, then send the Approve workflow action.
- This API is not supported for the Processor role or expense reports pending the Processor workflow step.
- Send Back to Employee: The report is sent back to the employee for revision. When the user resubmits the report, it travels through the entire workflow again.
- Recall to Employee: This workflow action is initiated by the employee, and is only available after the report has been submitted. This workflow action may not be available to some clients due to configuration.
WARNING: Prior to calling this endpoint the Caller must check the Approval Status found in the ApprovalStatusName element in the response for Get Report Details to ensure the report is at the workflow step the Caller expects. Under no circumstance should a Caller make a call to this endpoint without being certain the report is at the workflow step the Caller expects.
Workflow Roles
Each workflow step in a workflow is associated with a workflow role. Professional clients can configure workflow steps and roles in the Workflows area of Expense Admin. The OAuth consumer is evaluated to determine which role(s) the consumer has in SAP Concur. There are two different types of workflow roles as described in the following sections.
System Role
The System role is used when the workflow actions can be completed programatically. Any workflow action can be completed this way, depending on the client's business process. The workflow role can be configured while adding the report workflow step. Some steps may require the System role. When using this role, the OAuth consumer must have the following user role:
- Standard/Developer Sandbox: Can Administer
- Professional: Company Admin or Web Services Administrator
The expense report owner must have an approver or processor assigned to them before the System role can make changes to their reports.
Approver Role
The Approver role is used when the workflow action should be completed by a particular user. Developers who want to present a list of reports to approve and send the workflow action when the reports have been evaluated by the approver use the Approver role. This role requires that a user with the correct SAP Concur role (Expense Approver, Authorized Approver, Cost Object Approver, or Expense Processor for Professional, or the Can Administer or Can Approve Reports roles for Standard) authenticates using Standard OAuth before supplying the workflow action. The user must also have access (be a valid approver or processor) for the supplied report ID.
Request
Request Parameters
Path Parameters
| Parameter | Required/Optional | Description |
|---|---|---|
| {workflowstepID}/workflowaction | required | The identifier for the desired workflow step and the workflowaction keyword. |
Example: https://www.concursolutions.com/api/expense/expensereport/v1.1/report/{workflowstepId}/workflowaction
URI Source: The URI is returned in the WorkflowActionURL element of the Get Report Details response.
Headers
Authorization Header
Authorization header with OAuth token for valid SAP Concur user. Required.
Content-Type Header
application/xml
Request Body
Request Schema
This request should contain a WorkflowAction parent element with the following child elements.
WorkflowAction Child Elements
| Element | Required/optional | Description |
|---|---|---|
| Action | required | The name of the workflow action. Possible values are: Approve, Send Back to Employee, or Recall to Employee. Must be one of the workflow actions available for the workflow step. Consult Expense Admin > Workflow to learn details. |
| Comment | required, for Send Back to Employee | Must be used with the Send Back to Employee workflow action. This comment is visible wherever report comments are available to the employee, approver, authorization request administrator, and/or processor. Max length: 2000 |
Response
Response Schema
This request will return an ActionStatus parent element with the following child elements.
ActionStatus Elements
| Element | Description |
|---|---|
| Message | The error message. Only appears if a workflow action error was generated. |
| Status | The status of the report workflow action. |
Examples
XML Example Request
POST https://www.concursolutions.com/api/expense/expensereport/v1.1/report/nx2WRNzp18$wjehk%wqEL6EDHRwi9r$paQS1UqyL6a454QitqQ/workflowaction HTTP/1.1
Authorization: OAuth {access token}
...
<WorkflowAction xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03">
<Action>Approve</Action>
<Comment>Approved via SAP Concur</Comment>
</WorkflowAction>
XML Example of Successful Response
<?xml version="1.0" encoding="utf-8"?>
<ActionStatus xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Message>SUCCESS!</Message>
<Status>SUCCESS!</Status>
</ActionStatus>
XML Example of Response with Error
<?xml version="1.0" encoding="utf-8"?>
<ActionStatus xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Message>The action cannot be executed because the item has recently been changed. Please refresh your list and try again.</Message>
<Status>FAILURE</Status>
</ActionStatus>
Expense Entry Attendee v3
- Retrieve All Entry-Attendee Associations Owned by the User
- Retrieve an Entry-Attendee Association by ID
- Create a New Entry-Attendee Association
- Update a Specified Entry-Attendee Association
- Delete a Specified Entry-Attendee Association
- Schema
Prior Versions
2.0 documentation is available here.
Retrieve All Entry-Attendee Associations Owned by the User
GET /api/v3.0/expense/entryattendeeassociations
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
entryID |
string |
query |
The ID of the entry for which to retrieve entry-attendee associations. |
offset |
string |
query |
The starting point of the next set of results, after the limit specified in the limit field has been reached. |
limit |
Int32 |
query |
The number of records to return. Default value: 25 |
user |
string |
query |
The login ID of the user who owns this entry-attendee association. The user must have the Web Services Admin role to use this parameter. |
Request URL
https://www.concursolutions.com/api/v3.0/expense/entryattendeeassociations?limit=15&user=ALL
JSON Example of a Successful Response
{
"Items": [
{
"EntryID": "gWidFO7ikXS264Tf3Z68NmcXdkxhcxezfzA",
"AttendeeID": "gWj3IHRYiHZGX4xP$s0YUWUyoUjss$pWV3z$pQ",
"Amount": 80,
"AssociatedAttendeeCount": 1,
"Custom1": null,
"Custom2": null,
"Custom3": null,
"Custom4": null,
"Custom5": null,
"ID": "gWgSNsCedFvv8LE1LrkughW9mAyCN",
"URI": "https://www.concursolutions.com/api/v3.0/expense/entryattendeeassociations/gWgSNsCedFvv8LE1LrkughW9mAyCN"
},
{
"EntryID": "gWidFO7ikXSi7DX4hlLTggJD76w1IvtEvWw",
"AttendeeID": "gWj3IHRYiHZGSG6M4xo0PEyYXAs8rHGfD$pQ",
"Amount": 120,
"AssociatedAttendeeCount": 1,
"Custom1": null,
"Custom2": null,
"Custom3": null,
"Custom4": null,
"Custom5": null,
"ID": "gWgOOsCJrozFymvWtfB5Ri1WD$ste9",
"URI": "https://www.concursolutions.com/api/v3.0/expense/entryattendeeassociations/gWgOOsCJrozFymvWtfB5Ri1WD$ste9"
}
]
}
Retrieve an Entry-Attendee Association by ID
GET /api/v3.0/expense/entryattendeeassociations/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required The ID of the entry-attendee association. |
user |
string |
query |
The login ID of the user who owns this entry-attendee association. The user must have the Web Services Admin role to use this parameter. |
Request URL
https://www.concursolutions.com/api/v3.0/expense/entryattendeeassociations/gWgSM%24s2kvfcQ8xC%24p6uaPsY6V6qB7FqOU
JSON Example of a Successful Response
{
"EntryID": "gWidFO7ikXV67u6QrT2w1Yhqzh4a8j$pEjCg",
"AttendeeID": "gWj3IHRYiHZOTjq8PONWIqyRFfGz4RoozoQ",
"Amount": 17.01,
"AssociatedAttendeeCount": 1,
"Custom1": null,
"Custom2": null,
"Custom3": null,
"Custom4": null,
"Custom5": null,
"ID": "gWgSM$s2kvfcQ8xC$p6uaPsY6V6qB7FqOU",
"URI": "https://www.concursolutions.com/api/v3.0/expense/entryattendeeassociations/gWgSM$s2kvfcQ8xC$p6uaPsY6V6qB7FqOU"
}
Create a New Entry-Attendee Association
POST /api/v3.0/expense/entryattendeeassociations
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
content |
- | body |
Required The EntryAttendeeAssociation object to create. |
Request URL
https://www.concursolutions.com/api/v3.0/expense/entryattendeeassociations
JSON Example of a Successful Response
{
"ID": "gWgSM$s2kvfcQ8xC$p6uaPsY6V6qB7FqOU",
"URI": "https://www.concursolutions.com/api/v3.0/expense/entryattendeeassociations/gWgSM$s2kvfcQ8xC$p6uaPsY6V6qB7FqOU"
}
Update a Specified Entry-Attendee Association
PUT /api/v3.0/expense/entryattendeeassociations/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required The ID of the entry-attendee association. |
content |
- | body |
Required The partial or complete EntryAttendeeAssociation object to update. |
Delete a Specified Entry-Attendee Association
DELETE /api/v3.0/expense/entryattendeeassociations/{id}
Request URL
https://www.concursolutions.com/api/v3.0/expense/entryattendeeassociations/gWgSM%24s2kvfcQ8xC%24p6uaPsY6V6qB7FqOU
JSON Example of a Successful Response
no content
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required The connection request ID. |
Schema
Entry Attendee Associations
| Name | Type | Format | Description |
|---|---|---|---|
Items |
array |
Entry Attendee Association | The result collection. |
NextPage |
string |
- | The URI of the next page of results, if any. |
Entry Attendee Association
| Name | Type | Format | Description |
|---|---|---|---|
Amount |
Decimal |
- | The portion of the entry transaction amount assigned to this attendee. |
AssociatedAttendeeCount |
Int32 |
- | The count of additional attendees associated with this attendee. A count greater than 1 means there are unnamed attendees associated with this attendee. |
AttendeeID |
string |
- | The unique identifier of the associated attendee. To obtain the attendee ID value, use the GET /expense/attendees endpoint. The value of the ID element in the response is the attendee ID. |
Custom1 through Custom5 |
string |
- | The details from the Custom fields. These fields may not have data, depending on the configuration. |
EntryID |
string |
- | The unique identifier of the associated entry. To obtain the attendee ID value, use the GET /expense/entries endpoint. The value of the ID element in the response is the entry ID. |
ID |
string |
- | The unique identifier of the resource. |
URI |
string |
- | The URI to the resource. |
Reports v3
- Retrieve reports owned by the user based on search criteria
- Retrieve a report by ID
- Create a new report
- Update a report
- Schema
Prior Versions
Retrieve reports owned by the user based on search criteria
GET /api/v3.0/expense/reports
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
offset |
string |
query |
Starting page offset |
limit |
Int32 |
query |
Number of records to return (default 25) |
user |
string |
query |
Optional. The login ID of the report owner(s) to use when searching for reports. If the value is set to LoginID, reports for the report owner with this login ID value are returned. If the value is set to ALL, reports for all report owners are returned. If this parameter is not specified, reports for the OAuth Consumer are returned. The access token owner (OAuth Consumer) must have the Web Services Admin role to use this parameter. |
approvalStatusCode |
string |
query |
The status code for the Approval Status. The values can include Concur Expense standard codes or custom codes. The Concur Expense standard code values are: A_AAFH - Report submission triggered an anomaly and fraud check; A_ACCO - Report is pending reviews; A_APPR - Report has been approved; A_EXTV - Report is pending external validation; A_FILE - Report has been submitted; A_NOTF - Report has not been submitted; A_PBDG - Report approval is pending Budget approval; A_PECO - Report approval is pending Cost object approval; A_PEND - Report is pending manager approval; A_PVAL - Report is pending prepayment validation; A_RESU - Report needs to be resubmitted; A_RHLD - Report submission is pending receipt images; A_TEXP - Report expired in approval queue. For custom codes, contact Concur Developer Support. |
paymentStatusCode |
string |
query |
The payment status code for the report. The values can include Concur Expense standard codes or custom codes. The Concur Expense standard code values are: P_HOLD - Report payment is on hold; P_NOTP - Report has not been paid; P_PAID - Report has been paid; P_PAYC - Payment is confirmed. Some or all of the report expenses have been paid; P_PROC - Report is in process to be paid. For custom codes, contact Concur Developer Support. |
currencyCode |
string |
query |
The 3-letter ISO 4217 currency code for the report currency. Example: USD. |
paymentType |
string |
query |
The unique identifier for the payment type that is the payment type for at least one expense entry in the report. Use PaymentTypeID from Response of GET Expense Group Configurations V3 to obtain valid payment types. |
reimbursementMethod |
string |
query |
The method the report owner will be reimbursed. VALUES: ADPPAYR - ADP Payroll; APCHECK - AP (Company Check); CNQRPAY - Expense Pay; PMTSERV - Other Payment Service. NOTE: PAY_PAL is NOT supported. |
approverLoginID |
string |
query |
The login ID for the report approver that is the current approver assigned to the report. |
expenseTypeCode |
string |
query |
The expense type code that is the expense type for at least one expense entry in the report. Use ExpenseTypeCode from Response of GET Expense Group Configurations V3. |
attendeeTypeCode |
string |
query |
The report contains expense entries that have attendees of the specified type. |
countryCode |
string |
query |
The report country. Maximum 2 characters. Format: The ISO 3166-1 alpha-2 country code. Example: United States is US. |
batchID |
string |
query |
The unique identifier for a payment batch where there is at least one report payee within the report. Use the BatchID from Response of GET Payment Batch List. |
vendorName |
string |
query |
The Vendor Description that is the vendor for at least one expense entry in the report. |
hasVAT |
Boolean |
query |
Determines if the report has at least one expense entry with VAT details. Format: true or false. |
hasImages |
Boolean |
query |
Determines if the report has at least one expense entry with an entry image or if there is a report image for this report. Format: true or false. |
hasAttendees |
Boolean |
query |
Determines if the report has at least one expense entry with an attendee. Format: true or false. |
hasBillableExpenses |
Boolean |
query |
The IsBillable flag for at least one expense entry in the report. Format: true or false. |
isTestUser |
Boolean |
query |
The report owner is a test user using the report for testing purposes in a non-production environment. Format: true or false. |
expenseGroupConfigID |
string |
query |
The unique identifier for the expense group configuration associated to the report's expense group. Use the ID from the Response of the Expense Group Configurations V3. |
entryTransactionDateBefore |
DateTime |
query |
The entry transaction date for at least one expense entry in the report is before this date. Accepted Formats: yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss.SSS |
entryTransactionDateAfter |
DateTime |
query |
The entry transaction date for at least one expense entry in the report is after this date. Accepted Formats: yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss.SSS |
createDateBefore |
DateTime |
query |
The report create date is before this date. Accepted Formats: yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss.SSS |
createDateAfter |
DateTime |
query |
The report create date is after this date. Accepted Formats: yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss.SSS |
userDefinedDateBefore |
DateTime |
query |
The report user defined date is before this date. Accepted Formats: yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss.SSS |
userDefinedDateAfter |
DateTime |
query |
The report user defined date is after this date. Accepted Formats: yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss.SSS |
submitDateBefore |
DateTime |
query |
The report submit date is before this date. Format: Accepted Formats: yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss.SSS |
submitDateAfter |
DateTime |
query |
The report submit date is after this date. Format: Accepted Formats: yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss.SSS |
processingPaymentDateBefore |
DateTime |
query |
The report processing payment date is before this date. Accepted Formats: yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss.SSS |
processingPaymentDateAfter |
DateTime |
query |
The report processing payment date is after this date. Accepted Formats: yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss.SSS |
paidDateBefore |
DateTime |
query |
The report paid date is before this date. Accepted Formats: yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss.SSS |
paidDateAfter |
DateTime |
query |
The report paid date is after this date. Accepted Formats: yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss.SSS |
modifiedDateBefore |
DateTime |
query |
The report modified date is before this date. Accepted Formats: yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss.SSS |
modifiedDateAfter |
DateTime |
query |
The report modified date is after this date. Accepted Formats: yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss.SSS |
Request URL
https://www.concursolutions.com/api/v3.0/expense/reports?limit=15&user=ALL
JSON example of a successful response
{
"Items": [
{
"Name": "Canadian Tax",
"Total": 1900,
"CurrencyCode": "CAD",
"Country": "CA",
"CountrySubdivision": "CA-BC",
"CreateDate": "2013-09-02T19:05:57.687",
"SubmitDate": "2013-09-02T19:18:35.537",
"ProcessingPaymentDate": "2013-09-02T19:40:48.533",
"PaidDate": "2013-09-02T19:46:01.57",
"ReceiptsReceived": false,
"UserDefinedDate": "2013-09-02T00:00:00",
"LastComment": "",
"OwnerLoginID": "CAtraveler@concurconnect2.com",
"OwnerName": "Canadian Traveler",
"ApproverLoginID": null,
"ApproverName": null,
"ApprovalStatusName": "Approved",
"ApprovalStatusCode": "A_APPR",
"PaymentStatusName": "Sent for Payment",
"PaymentStatusCode": "P_PAID",
"LastModifiedDate": "2013-09-02T19:46:01.98",
"PersonalAmount": 0,
"AmountDueEmployee": 1500,
"AmountDueCompanyCard": 0,
"TotalClaimedAmount": 1900,
"TotalApprovedAmount": 1900,
"LedgerName": "DEFAULT",
"PolicyID": "gWmINGEAkQoamAzOARD9NEBtuv0ppnbJ4lQ",
"EverSentBack": false,
"HasException": false,
"WorkflowActionUrl": "http://www.concursolutions.com/api/v3.0/expense/reports/report/gWpkOyRxJoH6lOiUHqNhW93UWxhOZZw/WorkFlowAction?limit=15&user=ALL",
"OrgUnit1": null,
"OrgUnit2": null,
"OrgUnit3": null,
"OrgUnit4": null,
"OrgUnit5": null,
"OrgUnit6": null,
"Custom1": null,
"Custom2": null,
"Custom3": null,
"Custom4": null,
"Custom5": null,
"Custom6": null,
"Custom7": null,
"Custom8": null,
"Custom9": null,
"Custom10": null,
"Custom11": null,
"Custom12": null,
"Custom13": null,
"Custom14": null,
"Custom15": null,
"Custom16": null,
"Custom17": null,
"Custom18": null,
"Custom19": null,
"Custom20": null,
"ID": "F4F027007E814C1CA70E",
"URI": "https://www.concursolutions.com/api/v3.0/expense/reports/F4F027007E814C1CA70E"
}
]
}
Retrieve a report by ID
GET /api/v3.0/expense/reports/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required Report ID |
user |
string |
query |
LoginID of the report owner needs to be specified in the query parameter when searching for specific report using ReportID. If Bearer Access token used in the API call is equal to the Bearer access token of the owner of the report, user parameter can be omitted. Parameter equal to ALL (user=ALL) is not allowed when operating on a single resource (single ReportID). |
Request URL
https://www.concursolutions.com/api/v3.0/expense/reports/39BD9F7C5C3F4986A6A5?user=jimadmin@concurconnect2.com
JSON example of a successful response
{
"Name": "Test 02",
"Total": 307.01,
"CurrencyCode": "USD",
"Country": "US",
"CountrySubdivision": null,
"CreateDate": "2016-04-04T23:33:08.21",
"SubmitDate": null,
"ProcessingPaymentDate": null,
"PaidDate": null,
"ReceiptsReceived": false,
"UserDefinedDate": "2016-04-04T00:00:00",
"LastComment": "",
"OwnerLoginID": "jimadmin@concurconnect2.com",
"OwnerName": "Jim Admin",
"ApproverLoginID": null,
"ApproverName": null,
"ApprovalStatusName": "Not Submitted",
"ApprovalStatusCode": "A_NOTF",
"PaymentStatusName": "Not Paid",
"PaymentStatusCode": "P_NOTP",
"LastModifiedDate": "2016-04-23T02:53:23.7",
"PersonalAmount": 0,
"AmountDueEmployee": 290,
"AmountDueCompanyCard": 0,
"TotalClaimedAmount": 307.01,
"TotalApprovedAmount": 307.01,
"LedgerName": "DEFAULT",
"PolicyID": "gWmINGEAkQoapyOLKfSdm0A9qK0ZVUvwolA",
"EverSentBack": false,
"HasException": true,
"WorkflowActionUrl": "",
"OrgUnit1": null,
"OrgUnit2": null,
"OrgUnit3": null,
"OrgUnit4": null,
"OrgUnit5": null,
"OrgUnit6": null,
"Custom1": null,
"Custom2": null,
"Custom3": null,
"Custom4": null,
"Custom5": null,
"Custom6": null,
"Custom7": null,
"Custom8": null,
"Custom9": null,
"Custom10": null,
"Custom11": null,
"Custom12": null,
"Custom13": null,
"Custom14": null,
"Custom15": null,
"Custom16": null,
"Custom17": null,
"Custom18": null,
"Custom19": null,
"Custom20": null,
"ID": "39BD9F7C5C3F4986A6A5",
"URI": "http://www.concursolutions.com/api/v3.0/expense/reports/39BD9F7C5C3F4986A6A5"
}
Create a new report
Note: Expense reports will be created under the user's default expense policy. If a user has two expense policies - default and purchasing card - passing the PolicyKey on the post body will be ignored by Expense. That is, the expense report will always be under the default expense policy.
POST /api/v3.0/expense/reports
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
content |
- | body |
Required Report object to create |
Update a report
Request URL
https://www.concursolutions.com/api/v3.0/expense/reports
JSON example of a successful response
{
"ID": "DD683A53018A4349B7CD",
"URI": "https://www.concursolutions.com/api/v3.0/expense/reports/DD683A53018A4349B7CD"
}
PUT /api/v3.0/expense/reports/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required The unique identifier for the report. |
content |
body |
Required The report object to update |
Schema
Reports
| Name | Type | Format | Description |
|---|---|---|---|
Items |
array |
Report | The result collection. |
NextPage |
string |
- | The URI of the next page of results, if any. |
Report
| Name | Type | Format | Description |
|---|---|---|---|
AmountDueCompanyCard |
Decimal |
- | The total amount due to the company card for the report. Maximum 23 characters. |
AmountDueEmployee |
Decimal |
- | The total amount due to the employee for the report. Maximum 23 characters. |
ApprovalStatusCode |
string |
- | The approval status code for the report. |
ApprovalStatusName |
string |
- | The report's approval status, in the OAuth consumer's language. |
ApproverLoginID |
string |
- | The Login ID of the report owner's expense approver. |
ApproverName |
string |
- | The name of the report owner's expense approver. |
Country |
string |
- | The report country. Maximum 2 characters. Format: The ISO 3166-1 alpha-2 country code. Example: United States is US. |
CountrySubdivision |
string |
- | The report country subdivision. Format: ISO 3166-2:2007 country subdivision. |
CreateDate |
DateTime |
- | The date the report was created. |
CurrencyCode |
string |
- | The 3-letter ISO 4217 currency code for the expense report currency. Examples: USD - US dollars; BRL - Brazilian real; CAD - Canadian dollar; CHF - Swiss franc; EUR - Euro; GBO - Pound sterling; HKD - Hong Kong dollar; INR - Indian rupee; MXN - Mexican peso; NOK - Norwegian krone; SEK - Swedish krona. |
Custom1 thorugh Custom20 |
CustomField |
- | The details from the Custom fields. These may not have data, depending on configuration. |
EverSentBack |
Boolean |
- | Whether the report has ever been sent back to the employee. Format: Y/N |
HasException |
Boolean |
- | Whether the report has exceptions. Format: Y/N |
ID |
string |
- | The unique identifier of the resource. |
LastComment |
string |
- | The text of the most recent comment on the report. |
LastModifiedDate |
DateTime |
- | The date the report header was last modified. |
LedgerName |
string |
- | The name of the expense report ledger. Maximum 20 characters. |
Name |
string |
- | Required The name of the report. |
OrgUnit1 through OrgUnit6 |
CustomField |
- | The details from the Org Unit fields. These may not have data, depending on configuration. |
OwnerLoginID |
string |
- | The Login ID of the user this report belongs to. |
OwnerName |
string |
- | The name of the expense report owner. |
PaidDate |
DateTime |
- | The date when all journal entries in the report was integrated with or extracted to the financial system. |
PaymentStatusCode |
string |
- | The code for the payment status of the report. |
PaymentStatusName |
string |
- | The report's payment status, in the OAuth consumer's language. |
PersonalAmount |
Decimal |
- | The total amount of expenses marked as personal. Maximum 23 characters. |
PolicyID |
string |
- | The unique identifier of the policy that applies to this report. Maximum 64 characters. User's default expense policy is being used when creating a new expense report. Note: Policy cannot be changed via the v3 Reports API. |
ProcessingPaymentDate |
DateTime |
- | The date that the report completed all approvals and was ready to be extracted for payment. |
ReceiptsReceived |
Boolean |
- | If Y, then this entry has been marked as confirmed by the Expense Processor. Format: Y/N |
SubmitDate |
DateTime |
- | The date the report was submitted. |
Total |
Decimal |
- | The total amount of the report. |
TotalApprovedAmount |
Decimal |
- | The total amount of approved expenses in the report. Maximum 23 characters. |
TotalClaimedAmount |
Decimal |
- | The total amount of all non-personal expenses in the report. Maximum 23 characters. |
URI |
string |
- | The URI to the resource. |
UserDefinedDate |
DateTime |
- | The date of the report assigned by the user. |
WorkflowActionUrl |
string |
- | The URL to post a workflow action to the report using the Post Report Workflow Action function. |
Custom Field
| Name | Type | Format | Description |
|---|---|---|---|
Code |
string |
- | For list fields, this is the list item code. |
ListItemID |
string |
- | For list fields, this is the list item ID. |
Type |
string |
- | The custom field type. Possible values: Amount, Boolean, ConnectedList, Date, Integer, List, Number, Text |
Value |
string |
- | The value in the Org Unit or Custom field. For list fields, this is the name of the list item. Maximum length: 48 characters |
Request URL
https://www.concursolutions.com/api/v3.0/expense/reports/39BD9F7C5C3F4986A6A5
JSON example of a successful response
no content
Allocations v4
The Allocations API can be used to read the allocations that belong to a specific expense on an expense report and modify an allocation on an existing expense in an expense report. This API can be used to change custom field attributes, etc.
Limitations: This API is only available to partners who have been granted access by SAP Concur. Access to this documentation does not provide access to the API.
- Products and Editions
- Scope Usage
- Dependencies
- Access Token Usage
- Retrieve allocations on a specific Expense ID and Report ID
- Retrieve an Allocation by ID
- Update an Allocation
- Schema
- Error
- Validation Errors
Prior Versions
- Allocations v3 documentation is available here
Products and Editions
- Concur Expense Professional Edition
- Concur Expense Standard Edition
Scope Usage
Required Scopes:
| Name | Description | Endpoint |
|---|---|---|
expense.report.read |
Get information about expense reports. | GET |
expense.report.readwrite |
Read and write expense report headers. | PATCH |
user.read |
Get User Information, necessary for userID. |
GET |
Optional Scope:
| Name | Description | Endpoint |
|---|---|---|
spend.listitem.read |
Read only access to spend list items listItemId. |
GET |
spend.list.read |
Read only access to spend list and category details. | GET |
Dependencies
SAP Concur clients must purchase Concur Expense in order to use this API. This API requires the Identity v4 API which is currently only available to approved early access partners. Please contact your SAP Concur representative for more information.
Access Token Usage
This API supports both company level and user level access tokens.
Retrieve Allocations of an Expense ID on a Specific Report ID
Retrieves the allocations that belong to a specific expense ID on a specific report ID.
Scopes
expense.report.read - Refer to Scope Usage for full details.
Request
URI Template
https://{datacenterURI}/expensereports/v4/users/{userID}/context/{contextType}/reports/{reportId}/expenses/{expenseId}/allocations
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
userID |
string |
- | Required The unique identifier of the SAP Concur user. Use Identity v4 API to retrieve the userID. |
contextType |
string |
- | Required The access level of the SAP Concur user, which determines the form fields they can view/modify. Supported value: TRAVELER |
reportId |
string |
- | Required The unique identifier of the report to which the expense entry belongs whose allocations are being retrieved. |
expenseId |
string |
- | Required The unique identifier of the expense entry whose allocations are being retrieved. |
Headers
- RFC 7231 Accept-Language
- RFC 7231 Content-Type
- RFC 7231 Content-Encoding
- RFC 7234 Cache-Control
- RFC 7232 If-Modified-Since
- RFC 7231 Accept-Encoding
- RFC 7235 Authorization - Bearer Token that identifies the caller. This is the Company or User access token.
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
Response
Status Codes
Headers
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
Payload
Example
Request
curl --location --request GET 'https://us.api.concursolutions.com/expensereports/v4/users/32c2fcc3-b2e8-4907-9672-5b3f49b1c643/context/TRAVELER/reports/764428DD6A664AF0BFCB/expenses/29EE3C62F5D844458828A5C1086072D1/allocations' \
--header 'Authorization: Bearer {access_token}' \
--header 'Concur-CorrelationId: Expense-Allocation-test' \
--header 'Content-Type: application/json'
Response
200 OK
[
{
"customData": [
{
"id": "custom9",
"value": "D3954B47BCEC9446A4FFC49E0000B46E",
"isValid": true
}
],
"allocationId": "3BBB494511E1C74DA04469C45B039871",
"accountCode": "Pending Client",
"overLimitAccountCode": null,
"allocationAmount": {
"value": 250.00,
"currencyCode": "USD"
},
"approvedAmount": {
"value": 250.00,
"currencyCode": "USD"
},
"claimedAmount": {
"value": 250.00,
"currencyCode": "USD"
},
"expenseId": "29EE3C62F5D844458828A5C1086072D1",
"isSystemAllocation": false,
"isPercentEdited": false,
"percentage": 50.00000000
},
{
"customData": [
{
"id": "custom9",
"value": "88EACA3116581248BCE27956DE67647D",
"isValid": true
}
],
"allocationId": "4DB06B4360E31443AD43ED52B2AE007E",
"accountCode": "Pending Client",
"overLimitAccountCode": null,
"allocationAmount": {
"value": 250.00,
"currencyCode": "USD"
},
"approvedAmount": {
"value": 250.00,
"currencyCode": "USD"
},
"claimedAmount": {
"value": 250.00,
"currencyCode": "USD"
},
"expenseId": "29EE3C62F5D844458828A5C1086072D1",
"isSystemAllocation": false,
"isPercentEdited": false,
"percentage": 50.00000000
}
]
Retrieve an Allocation by ID
Retrieves the details of the specific allocation of an expense entry on a report.
Scopes
expense.report.read - Refer to Scope Usage for full details.
Request
URI Template
https://{datacenterURI}/expensereports/v4/users/{userID}/context/{contextType}/reports/{reportId}/allocations/{allocationId}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
userID |
string |
- | Required The unique identifier of the SAP Concur user. Use Identity v4 API to retrieve the userID. |
contextType |
string |
- | Required The access level of the SAP Concur user, which determines the form fields they can view/modify. Supported values: TRAVELER, PROXY |
reportId |
string |
- | Required The unique identifier of the report to which this allocation belongs. |
allocationId |
string |
- | Required The unique identifier of the allocation that is being retrieved. |
Headers
- RFC 7231 Accept-Language
- RFC 7231 Content-Type
- RFC 7231 Content-Encoding
- RFC 7234 Cache-Control
- RFC 7232 If-Modified-Since
- RFC 7231 Accept-Encoding
- RFC 7235 Authorization - Bearer Token that identifies the caller. This is the Company or User access token.
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
Response
Status Codes
Headers
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
Payload
Example
Request
curl --location --request GET 'https://us.api.concursolutions.com/expensereports/v4/users/32c2fcc3-b2e8-4907-9672-5b3f49b1c643/context/TRAVELER/reports/764428DD6A664AF0BFCB/allocations/3BBB494511E1C74DA04469C45B039871' \
--header 'Authorization: Bearer {access_token}' \
--header 'Concur-CorrelationId: Expense-Allocation-test' \
--header 'Content-Type: application/json'
Response
200 OK
{
"customData": [
{
"id": "custom9",
"value": "D3954B47BCEC9446A4FFC49E0000B46E",
"isValid": true
}
],
"allocationId": "3BBB494511E1C74DA04469C45B039871",
"accountCode": "Pending Client",
"overLimitAccountCode": null,
"allocationAmount": {
"value": 250.00,
"currencyCode": "USD"
},
"approvedAmount": {
"value": 250.00,
"currencyCode": "USD"
},
"claimedAmount": {
"value": 250.00,
"currencyCode": "USD"
},
"expenseId": "29EE3C62F5D844458828A5C1086072D1",
"isSystemAllocation": false,
"isPercentEdited": false,
"percentage": 50.00000000
}
Update a Specific Allocation
Updates the attributes of a specific allocation.
Scopes
expense.report.readwrite - Refer to Scope Usage for full details.
Request
URI Template
https://{datacenterURI}/expensereports/v4/users/{userID}/context/{contextType}/reports/{reportId}/allocations/{allocationId}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
userID |
string |
- | Required The unique identifier of the SAP Concur user. Use Identity v4 API to retrieve the userID. |
contextType |
string |
- | Required The access level of the SAP Concur user, which determines the form fields they can view/modify. Supported values: TRAVELER, PROXY |
reportId |
string |
- | Required The unique identifier of the report to which this allocation belongs. |
allocationId |
string |
- | Required The unique identifier of the allocation that is being retrieved. |
Headers
- RFC 7231 Accept-Language
- RFC 7231 Content-Type
- RFC 7231 Content-Encoding
- RFC 7234 Cache-Control
- RFC 7232 If-Modified-Since
- RFC 7231 Accept-Encoding
- RFC 7235 Authorization - Bearer Token that identifies the caller. This is the Company or User access token.
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
REST Design Specification
PATCH operations in Expense Reports v4 conform to the JSON Merge Patch specification:
Payload
Response
Status Codes
- 204 No Content
- 400 Bad Request
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found
- 500 Internal Server Error
Headers
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
Payload
Example
Request
curl --location --request PATCH 'https://us.api.concursolutions.com/expensereports/v4/users/32C2FCC3-B2E8-4907-9672-5B3F49B1C643/context/TRAVELER/reports/764428DD6A664AF0BFCB/allocations/3BBB494511E1C74DA04469C45B039871' \
--header 'Authorization: Bearer {access_token}' \
--header 'Concur-CorrelationId: Viswa test' \
--header 'Content-Type: application/json' \
--header 'Content-Type: text/plain' \
--data-raw '{
"allocation":{
"customData": [
{
"id": "custom9",
"value": "058713001E2CD943824280D9275FDC3F",
"isValid": true
}
]
},
"expenseIds": ["29EE3C62F5D844458828A5C1086072D1"]
}'
Response
204 No Content
Schema
ReportAllocationResponse
| Name | Type | Format | Description |
|---|---|---|---|
accountCode |
string |
- | The ledger account code associated with the allocation. |
allocationAmount |
Amount |
- | The amount of the allocation. |
allocationId |
string |
- | Required The unique identifier of the allocation. |
approvedAmount |
Amount |
- | The pro-rated amount of the allocation approved for reimbursement based on the approved expense amount. |
claimedAmount |
Amount |
- | The amount of the allocation requested for reimbursement. |
customData |
CustomData |
- | The details from the customData fields. These fields may not have data, depending on the configuration. |
expenseId |
string |
- | Required The unique identifier of the expense associated with the allocation. |
isPercentEdited |
boolean |
true/false |
Required Whether the allocation percent has been edited. |
isSystemAllocation |
boolean |
true/false |
Required Whether the allocation is a system allocation, usually hidden from the user. If displayed to the user, should be read-only. |
overLimitAccountCode |
string |
- | The ledger account code associated with the allocation if it exceeds a pre-defined threshold, for example, the user’s travel allowance limit. |
percentage |
number |
double |
Required The percentage of the total expense that this allocation represents. |
CustomData
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
- | Required The unique identifier of the custom field. Examples: custom1, orgUnit1 |
isValid |
boolean |
true/false |
Whether the value returned is valid or not. This value is returned for custom fields of all data types and is specifically evaluated for list items to represent the current status. Default: true |
value |
string |
- | The value of the custom field. This field can have values for all the supported data types such as text, integer, boolean and listItemId. Maximum length: 48 characters |
Amount
| Name | Type | Format | Description |
|---|---|---|---|
currencyCode |
string |
- | Required The 3-letter ISO 4217 currency code for the expense report currency, based on the user's assigned reimbursement currency when the report was created. Examples: USD - US dollars; BRL - Brazilian real; CAD - Canadian dollar; CHF - Swiss franc; EUR - Euro; GBO - Pound sterling; HKD - Hong Kong dollar; INR - Indian rupee; MXN - Mexican peso; NOK - Norwegian krone; SEK - Swedish krona |
value |
number |
double |
Required The amount in the defined currency. |
UpdateReportAllocation
| Name | Type | Format | Description |
|---|---|---|---|
allocation |
UpdateAllocation |
- | Required This is an allocation custom data object to be updated. |
expenseIds |
string |
- | Required This is an array of unique identifiers of expenses within this report that are being updated. |
UpdateAllocation
| Name | Type | Format | Description |
|---|---|---|---|
customData |
CustomData | - | The details from the customData fields. These fields may not have data, depending on the configuration. |
Link
| Name | Type | Format | Description |
|---|---|---|---|
deprecation |
string |
- | - |
href |
string |
- | Required The URL of the related HATEOAS link that you can use for subsequent calls. |
hreflang |
string |
- | - |
isTemplated |
boolean |
true/false |
Required Whether the href is parameterized. |
media |
string |
- | - |
method |
string |
- | Required The HTTP method required for the related call. |
rel |
string |
- | Required The link relationship that describes how the href relates to the API call. |
title |
string |
- | - |
type |
string |
- | - |
ErrorMessage
| Name | Type | Format | Description |
|---|---|---|---|
errorId |
string |
- | The unique identifier of the error associated with the response. |
errorMessage |
string |
- | Required The detailed error message. |
httpStatus |
string |
- | Required The http response code and phrase for the response. |
path |
string |
- | Required The URI of the attempted request. |
timestamp |
string |
date-time |
Required The time when the error was captured. |
validationErrors |
ValidationError |
- | The validation error messages. |
ValidationError
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
- | The ID of the validation error. |
message |
string |
- | The detailed message of the validation error. |
source |
string |
- | The type of validation which failed. |
Comments v4
The Comments v4 API is used to read the comments entered on the expense report header, or expenses of an existing expense report. This API is used to detail information about spending that occurs out of policy, which is justified by the report owner, or inaccuracies pointed out by the approvers of the expense report.
Limitations: This API is only available to partners who have been granted access by SAP Concur. Access to this documentation does not provide access to the API.
- Prior Versions
- Products and Editions
- Scope Usage
- Dependencies
- Access Token Usage
- Retrieve Report Header Comments
- Retrieve Expense Comments
- Schema
Prior Versions
- Reports v2 documentation is available here.
Products and Editions
- Concur Expense Professional Edition
- Concur Expense Standard Edition
Scope Usage
Required Scopes:
| Name | Description | Endpoint |
|---|---|---|
expense.report.read |
Get information about expense reports. | GET |
user.read |
Get User Information, necessary for userID. |
GET |
Optional Scope:
| Name | Description | Endpoint |
|---|---|---|
expense.report.readwrite |
Read and write expense report headers. | PATCH |
expense.report.workflowstatus.write |
Approve or Send Back the Report in the workflow | PATCH |
Dependencies
SAP Concur clients must purchase Concur Expense in order to use this API. This API requires the Identity v4 API which is currently only available to approved early access partners. Please contact your SAP Concur representative for more information.
Access Token Usage
This API supports both company level and user level access tokens.
Retrieve Report Header Comments
Retrieves the comments on the specific report header.
Scopes
expense.report.read - Refer to Scope Usage for full details.
Request
URI Template
https://{datacenterURI}/expensereports/v4/users/{userID}/context/{contextType}/reports/{reportId}/comments
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
userID |
string |
- | Required The unique identifier of the SAP Concur user. Use Identity v4 to retrieve the userID. |
contextType |
string |
- | Required The access level of the SAP Concur user, which determines the form fields they can view/modify. Supported values: TRAVELER, PROXY |
reportId |
string | - | Required The unique identifier of the report that is being read. |
Headers
- RFC 7231 Accept-Language
- RFC 7231 Content-Type
- RFC 7231 Content-Encoding
- RFC 7234 Cache-Control
- RFC 7232 If-Modified-Since
- RFC 7231 Accept-Encoding
- RFC 7235 Authorization - Bearer Token that identifies the caller. This is the Company or User access token.
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
Response
Status Codes
Headers
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
Payload
Example
Request
curl --location --request GET 'https://us.api.concursolutions.com/expensereports/v4/users/32C2FCC3-B2E8-4907-9672-5B3F49B1C643/context/TRAVELER/reports/764428DD6A664AF0BFCB/comments' \
--header 'Authorization: Bearer {access_token}' \
--header 'Concur-CorrelationId: Expense-Report-test' \
--header 'Content-Type: application/json'
Response
200 OK
[
{
"comment": "This is an expense report for office supplies",
"creationDate": "2021-03-17T22:29:50.090Z",
"author": {
"firstName": "Concur",
"lastName": "Administrator",
"middleInitial": ""
},
"createdForEmployeeId": "32c2fcc3-b2e8-4907-9672-5b3f49b1c643",
"createdForEmployee": {
"firstName": "Tester",
"lastName": "Insert",
"middleInitial": "A"
},
"isLatest": true
}
]
Retrieve Expense Comments
Retrieves the comments on the specific expense within an expense report.
Scopes
expense.report.read - Refer to Scope Usage for full details.
Request
URI Template
https://{datacenterURI}/expensereports/v4/users/{userID}/context/{contextType}/reports/{reportId}/expenses/{expenseId}/comments
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
userID |
string |
- | Required The unique identifier of the SAP Concur user. Use Identity v4 to retrieve the userID. |
contextType |
string |
- | Required The access level of the SAP Concur user, which determines the form fields they can view/modify. Supported values: TRAVELER, PROXY |
reportId |
string | - | Required The unique identifier of the report to which this expense entry belongs. |
expenseId |
string |
- | Required The unique identifier of the expense entry to which the comments belong. |
Headers
- RFC 7231 Accept-Language
- RFC 7231 Content-Type
- RFC 7231 Content-Encoding
- RFC 7234 Cache-Control
- RFC 7232 If-Modified-Since
- RFC 7231 Accept-Encoding
- RFC 7235 Authorization - Bearer Token that identifies the caller. This is the Company or User access token.
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
Response
Status Codes
Headers
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
Payload
Example
Request
curl --location --request GET 'https://us.api.concursolutions.com/expensereports/v4/users/32C2FCC3-B2E8-4907-9672-5B3F49B1C643/context/TRAVELER/reports/764428DD6A664AF0BFCB/expenses/84FCBB92BD4E5342B849DAC29FD163A1/comments' \
--header 'Authorization: Bearer {access_token}' \
--header 'Concur-CorrelationId: Expense-Report-test' \
--header 'Content-Type: application/json'
Expense Comments Response
200 OK
[
{
"comment": "This expense is allowed due to the pandemic",
"creationDate": "2021-03-17T23:05:40.340Z",
"author": {
"firstName": "Concur",
"lastName": "Administrator",
"middleInitial": ""
},
"createdForEmployeeId": "32c2fcc3-b2e8-4907-9672-5b3f49b1c643",
"createdForEmployee": {
"firstName": "Tester",
"lastName": "Insert",
"middleInitial": "A"
},
"isLatest": true
}
]
Schema
Report Header Comments
| Name | Type | Format | Description |
|---|---|---|---|
commentDetails |
array |
commentDetails |
A key linking to another schema for the format. |
Expense Comments
| Name | Type | Format | Description |
|---|---|---|---|
commentDetails |
array |
commentDetails |
A key linking to another schema for the format. |
commentDetails
| Name | Type | Format | Description |
|---|---|---|---|
author |
Employee |
- | Required The comment author's name. |
comment |
string |
- | Required The comments input on the report by all users. |
createdForEmployee |
Employee |
- | Required The name of the employee the comment was created on behalf of. This would differ from the comment author only in the case of delegates creating the comment. |
createdForEmployeeId |
string |
- | Required The unique identifier of the employee the comment was created on behalf of. This would differ from the comment author only in the case of delegates creating the comment. |
creationDate |
string |
YYYY-MM-DDTHH:mm:ssZ.SSS'Z' |
Required The UTC datetime when the comment was created on the report or expense. |
isLatest |
boolean |
true/false |
Required If true, this attribute represents the latest comment by the user. |
Employee
| Name | Type | Format | Description |
|---|---|---|---|
firstName |
string |
- | First name of the employee. |
lastName |
string |
- | Last name of the employee. |
middleInitial |
string |
- | Middle initial of the employee. |
Error Message
| Name | Type | Format | Description |
|---|---|---|---|
errorId |
string |
- | The unique identifier of the error associated with the response. |
errorMessage |
string |
- | Required The detailed error message. |
httpStatus |
string |
- | Required The http response code and phrase for the response. |
path |
string |
- | Required The URI of the attempted request. |
timestamp |
string |
date-time |
Required The time when the error was captured. |
validationErrors |
ValidationError |
- | The validation error messages. |
Validation Error
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
- | The ID of the validation error. |
message |
string |
- | The detailed message of the validation error. |
source |
string |
- | The type of validation which failed. |
Expenses v4
The Expenses API can be used to read the expenses that belong to a specific expense report and modify an expense on an existing expense report. This API can be used to change attributes like transaction date, transaction amount, location, etc.
Limitations: This API is only available to partners who have been granted access by SAP Concur. Access to this documentation does not provide access to the API.
- Products and Editions
- Scope Usage
- Dependencies
- Access Token Usage
- Retrieve expenses on a specific Report ID
- Retrieve an Expense by ID
- Update an Expense in an unsubmitted report
- Update an Expense in a submitted report
- Schema
- Update Report Expense Compact Schema
- Report Expense Summary
- Report Expense Detail
- Custom Data
- Amount
- Expense Source Identifiers
- Exchange Rate
- Expense Type
- Location
- Mileage
- Payment Type
- Receipt Type
- Travel
- Travel Allowance
- Vendor
- Update Report Expense
- Smart Expense
- Tax
- Expense Tax
- eReceipt
- Hotel eReceipt
- Car eReceipt
- Expense Attendee
- Expense Attendees
- Trip
- Hotel Trip
- Air Trip
- Ride Trip
- Car Trip
- Link
- Error
- Validation Errors
Prior Versions
- Expense entry v1.1 (Deprecated) documentation is available here
- Expense Entry v3 documentation is available here
Products and Editions
- Concur Expense Professional Edition
- Concur Expense Standard Edition
Scope Usage
Required Scopes:
| Name | Description | Endpoint |
|---|---|---|
expense.report.read |
Get information about expense reports. | GET |
expense.report.readwrite |
Read and write expense report headers. | PATCH |
user.read |
Get User Information, necessary for userID. |
GET |
Optional Scope:
| Name | Description | Endpoint |
|---|---|---|
spend.listitem.read |
Read only access to spend list items listItemId. |
GET |
spend.list.read |
Read only access to spend list and category details. | GET |
Dependencies
SAP Concur clients must purchase Concur Expense in order to use this API. This API requires the Identity v4 API which is currently only available to approved early access partners. Please contact your SAP Concur representative for more information.
Access Token Usage
This API supports both company level and user level access tokens.
Retrieve Expenses on a Specific Report ID
Retrieves the expenses that belong to a specific report ID.
Scopes
expense.report.read - Refer to Scope Usage for full details.
Request
URI Template
https://{datacenterURI}/expensereports/v4/users/{userID}/context/{contextType}/reports/{reportId}/expenses
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
userID |
string |
- | Required The unique identifier of the SAP Concur user. Use Identity v4 API to retrieve the userID. |
contextType |
string |
- | Required The access level of the SAP Concur user, which determines the form fields they can view/modify. Supported value: TRAVELER |
reportId |
string |
- | Required The unique identifier of the report that is being read. |
Headers
- RFC 7231 Accept-Language
- RFC 7231 Content-Type
- RFC 7231 Content-Encoding
- RFC 7234 Cache-Control
- RFC 7232 If-Modified-Since
- RFC 7231 Accept-Encoding
- RFC 7235 Authorization - Bearer Token that identifies the caller. This is the Company or User access token.
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
Response
Status Codes
Headers
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
Payload
Example
Request
curl --location --request GET 'https://us.api.concursolutions.com/expensereports/v4/users/32C2FCC3-B2E8-4907-9672-5B3F49B1C643/context/TRAVELER/reports/764428DD6A664AF0BFCB/expenses' \
--header 'Authorization: Bearer {access_token}' \
--header 'Concur-CorrelationId: Expense-Report-test' \
--header 'Content-Type: application/json'
Response
200 OK
[
{
"expenseId": "84FCBB92BD4E5342B849DAC29FD163A1",
"approverAdjustedAmount": {
"value": 25.00000000,
"currencyCode": "USD"
},
"allocationState": "NOT_ALLOCATED",
"allocationSetId": null,
"approvedAmount": {
"value": 25.00000000,
"currencyCode": "USD"
},
"businessPurpose": "test",
"claimedAmount": {
"value": 25.00000000,
"currencyCode": "USD"
},
"ereceiptImageId": null,
"exchangeRate": {
"value": 1.00000000000000,
"operation": "MULTIPLY"
},
"expenseSourceIdentifiers": null,
"expenseType": {
"id": "LUNCH",
"name": "Lunch",
"code": "OTHER",
"isDeleted": false
},
"hasBlockingExceptions": false,
"hasExceptions": false,
"hasMissingReceiptDeclaration": false,
"isAutoCreated": false,
"imageCertificationStatus": null,
"isImageRequired": true,
"isPaperReceiptRequired": false,
"isPersonalExpense": false,
"location": {
"id": "04F3ED00D0884F4681628E3337A5B515",
"name": "Bellevue, Washington",
"city": "Bellevue",
"countrySubDivisionCode": "US-WA",
"countryCode": "US"
},
"paymentType": {
"id": "CASH",
"name": "Cash",
"code": "CASH"
},
"postedAmount": {
"value": 25.00000000,
"currencyCode": "USD"
},
"receiptImageId": null,
"ticketNumber": null,
"transactionAmount": {
"value": 25.00000000,
"currencyCode": "USD"
},
"transactionDate": "2020-03-11",
"travelAllowance": {
"dailyLimitAmount": null,
"dailyTravelAllowanceId": null,
"isExpensePartOfTravelAllowance": false
},
"vendor": null,
"attendeeCount": 1,
"links": [
{
"rel": "self",
"href": "https://us.api.concursolutions.com/expensereports/v4/users/32c2fcc3-b2e8-4907-9672-5b3f49b1c643/context/TRAVELER/reports/764428DD6A664AF0BFCB/expenses/84FCBB92BD4E5342B849DAC29FD163A1",
"hreflang": null,
"media": null,
"title": null,
"type": null,
"deprecation": null,
"method": "GET",
"isTemplated": false
}
]
},
{
"expenseId": "29EE3C62F5D844458828A5C1086072D1",
"approverAdjustedAmount": {
"value": 500.00000000,
"currencyCode": "USD"
},
"allocationState": "NOT_ALLOCATED",
"allocationSetId": null,
"approvedAmount": {
"value": 500.00000000,
"currencyCode": "USD"
},
"businessPurpose": "Facility supplies",
"claimedAmount": {
"value": 500.00000000,
"currencyCode": "USD"
},
"ereceiptImageId": null,
"exchangeRate": {
"value": 1.00000000000000,
"operation": "MULTIPLY"
},
"expenseSourceIdentifiers": null,
"expenseType": {
"id": "OFCSP",
"name": "Office Supplies",
"code": "OTHER",
"isDeleted": false
},
"hasBlockingExceptions": false,
"hasExceptions": false,
"hasMissingReceiptDeclaration": false,
"isAutoCreated": false,
"imageCertificationStatus": null,
"isImageRequired": true,
"isPaperReceiptRequired": false,
"isPersonalExpense": false,
"location": {
"id": "0BC6B782B77349898E2CA814F5B57C08",
"name": "Seattle, Washington",
"city": "Seattle",
"countrySubDivisionCode": "US-WA",
"countryCode": "US"
},
"paymentType": {
"id": "1022",
"name": "Mastercard",
"code": "CBCP"
},
"postedAmount": {
"value": 500.00000000,
"currencyCode": "USD"
},
"receiptImageId": null,
"ticketNumber": null,
"transactionAmount": {
"value": 500.00000000,
"currencyCode": "USD"
},
"transactionDate": "2020-03-11",
"travelAllowance": {
"dailyLimitAmount": null,
"dailyTravelAllowanceId": null,
"isExpensePartOfTravelAllowance": false
},
"vendor": {
"id": null,
"name": null,
"description": "Antioch Construction"
},
"attendeeCount": 0,
"links": [
{
"rel": "self",
"href": "https://us.api.concursolutions.com/expensereports/v4/users/32c2fcc3-b2e8-4907-9672-5b3f49b1c643/context/TRAVELER/reports/764428DD6A664AF0BFCB/expenses/29EE3C62F5D844458828A5C1086072D1",
"hreflang": null,
"media": null,
"title": null,
"type": null,
"deprecation": null,
"method": "GET",
"isTemplated": false
}
]
}
]
Retrieve an Expense by ID
Retrieves the details of the specific expense entry on a report.
Scopes
expense.report.read - Refer to Scope Usage for full details.
Request
URI Template
https://{datacenterURI}/expensereports/v4/users/{userID}/context/{contextType}/reports/{reportId}/expenses/{expenseId}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
userID |
string |
- | Required The unique identifier of the SAP Concur user. Use Identity v4 API to retrieve the userID. |
contextType |
string |
- | Required The access level of the SAP Concur user, which determines the form fields they can view/modify. Supported value: TRAVELER, PROXY |
reportId |
string |
- | Required The unique identifier of the report to which this expense entry belongs. |
expenseId |
string |
- | Required The unique identifier of the expense entry that is being read. |
Headers
- RFC 7231 Accept-Language
- RFC 7231 Content-Type
- RFC 7231 Content-Encoding
- RFC 7234 Cache-Control
- RFC 7232 If-Modified-Since
- RFC 7231 Accept-Encoding
- RFC 7235 Authorization - Bearer Token that identifies the caller. This is the Company or User access token.
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
Response
Status Codes
Headers
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
Payload
Example
Request
curl --location --request GET 'https://us.api.concursolutions.com/expensereports/v4/users/32C2FCC3-B2E8-4907-9672-5B3F49B1C643/context/TRAVELER/reports/764428DD6A664AF0BFCB/expenses/84FCBB92BD4E5342B849DAC29FD163A1' \
--header 'Authorization: Bearer {access_token}' \
--header 'Concur-CorrelationId: Expense-Report-test' \
--header 'Content-Type: application/json'
Response
200 OK
{
"expenseId": "84FCBB92BD4E5342B849DAC29FD163A1",
"approverAdjustedAmount": {
"value": 25.00000000,
"currencyCode": "USD"
},
"allocationState": "NOT_ALLOCATED",
"allocationSetId": null,
"approvedAmount": {
"value": 25.00000000,
"currencyCode": "USD"
},
"businessPurpose": "test",
"claimedAmount": {
"value": 25.00000000,
"currencyCode": "USD"
},
"ereceiptImageId": null,
"exchangeRate": {
"value": 1.00000000000000,
"operation": "MULTIPLY"
},
"expenseSourceIdentifiers": null,
"expenseType": {
"id": "ONLIN",
"name": "Online Fees",
"code": "OTHER",
"isDeleted": false
},
"hasBlockingExceptions": false,
"hasExceptions": false,
"hasMissingReceiptDeclaration": false,
"isAutoCreated": false,
"imageCertificationStatus": null,
"isImageRequired": true,
"isPaperReceiptRequired": false,
"isPersonalExpense": false,
"location": {
"id": "04F3ED00D0884F4681628E3337A5B515",
"name": "Bellevue, Washington",
"city": "Bellevue",
"countrySubDivisionCode": "US-WA",
"countryCode": "US"
},
"paymentType": {
"id": "CASH",
"name": "Cash",
"code": "CASH"
},
"postedAmount": {
"value": 25.00000000,
"currencyCode": "USD"
},
"receiptImageId": null,
"ticketNumber": null,
"transactionAmount": {
"value": 25.00000000,
"currencyCode": "USD"
},
"transactionDate": "2020-03-11",
"travelAllowance": {
"dailyLimitAmount": null,
"dailyTravelAllowanceId": null,
"isExpensePartOfTravelAllowance": false
},
"vendor": null,
"attendeeCount": 1,
"links": [
{
"rel": "self",
"href": "https://us.api.concursolutions.com/expensereports/v4/users/32c2fcc3-b2e8-4907-9672-5b3f49b1c643/context/TRAVELER/reports/764428DD6A664AF0BFCB/expenses/84FCBB92BD4E5342B849DAC29FD163A1",
"hreflang": null,
"media": null,
"title": null,
"type": null,
"deprecation": null,
"method": "GET",
"isTemplated": false
}
],
"budgetAccrualDate": null,
"authorizationRequestExpenseId": null,
"customData": [
{
"id": "custom9",
"value": "AB8596D91C994F4DBBD820D6DCBDC599",
"isValid": true,
"listItemUrl": "https://us.api.concursolutions.com/list/v4/items?id=AB8596D91C994F4DBBD820D6DCBDC599"
}
],
"expenseTaxSummary": {
"totalTaxPostedAmount": {
"value": 0E-8,
"currencyCode": "USD"
},
"totalTaxAdjustedAmount": {
"value": 0E-8,
"currencyCode": "USD"
},
"totalReclaimPostedAmount": {
"value": 0E-8,
"currencyCode": "USD"
},
"totalReclaimAdjustedAmount": {
"value": 0E-8,
"currencyCode": "USD"
},
"netTaxAmount": {
"value": 25.00000000,
"currencyCode": "USD"
},
"netAdjustedTaxAmount": {
"value": 25.00000000,
"currencyCode": "USD"
},
"netReclaimAmount": {
"value": 25.00000000,
"currencyCode": "USD"
},
"netReclaimAdjustedAmount": {
"value": 25.00000000,
"currencyCode": "USD"
},
"vatTaxTotal": null
},
"isExcludedFromCashAdvanceByUser": false,
"isExpenseBillable": false,
"isExpenseRejected": false,
"isPaperReceiptReceived": false,
"merchantTaxId": null,
"mileage": null,
"parentExpenseId": null,
"receiptType": {
"id": "N",
"status": "No Receipt"
},
"taxRateLocation": "HOME",
"travel": null,
}
Update a Specific Expense Entry in an Unsubmitted Report
Updates the specified expense in an unsubmitted report and is flexible for modifying multiple attributes in the schema detailed below
Scopes
expense.report.readwrite - Refer to Scope Usage for full details.
Request
URI Template
https://{datacenterURI}/expensereports/v4/users/{userID}/context/{contextType}/reports/{reportId}/expenses/{expenseId}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
userID |
string |
- | Required The unique identifier of the SAP Concur user. Use Identity v4 API to retrieve the userID. |
contextType |
string |
- | Required The access level of the SAP Concur user, which determines the form fields they can view/modify. Supported value: TRAVELER, PROXY |
reportId |
string |
- | Required The unique identifier of the report to which this expense entry belongs. |
expenseId |
string |
- | Required The unique identifier of the expense entry that is being read. |
Headers
- RFC 7231 Accept-Language
- RFC 7231 Content-Type
- RFC 7231 Content-Encoding
- RFC 7234 Cache-Control
- RFC 7232 If-Modified-Since
- RFC 7231 Accept-Encoding
- RFC 7235 Authorization - Bearer Token that identifies the caller. This is the Company or User access token.
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
REST Design Specification
PATCH operations in Expense Reports v4 conform to the JSON Merge Patch specification:
Payload
Response
Status Codes
- 204 No Content
- 400 Bad Request
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found
- 500 Internal Server Error
Headers
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
Payload
Example
Request
curl --location --request PATCH 'https://us.api.concursolutions.com/expensereports/v4/users/32C2FCC3-B2E8-4907-9672-5B3F49B1C643/context/TRAVELER/reports/764428DD6A664AF0BFCB/expenses/84FCBB92BD4E5342B849DAC29FD163A1' \
--header 'Authorization: Bearer {access_token}' \
--header 'Concur-CorrelationId: Expense-Test' \
--header 'Content-Type: application/json' \
--header 'Content-Type: text/plain' \
--data-raw '{
"customData": [
{
"id": "custom09",
"value": "81188b39-605d-2d4f-b80b-43efa84a7b49",
"isValid": true
}
],
"businessPurpose":"Office Facility Supplies",
"transactionAmount":{
"value": 50.00000000,
"currencyCode": "USD"
},
"expenseSource":"OTHER"
}'
Response
204 No Content
Update a Specific Expense Entry in a Submitted Report
Updates the specified expense in an unsubmitted or submitted report and is restricted to modify 'Business Purpose' and 'Custom/Org unit' fields only.
Scopes
expense.report.readwrite - Refer to Scope Usage for full details.
Request
URI Template
https://{datacenterURI}/expensereports/v4/reports/{reportId}/expenses/{expenseId}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
reportId |
string |
- | Required The unique identifier of the report to which this expense entry belongs. |
expenseId |
string |
- | Required The unique identifier of the expense entry that is being read. |
Headers
- RFC 7231 Accept-Language
- RFC 7231 Content-Type
- RFC 7231 Content-Encoding
- RFC 7234 Cache-Control
- RFC 7232 If-Modified-Since
- RFC 7231 Accept-Encoding
- RFC 7235 Authorization - Bearer Token that identifies the caller. This is the Company or User access token.
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
REST Design Specification
PATCH operations in Expense Reports v4 conform to the JSON Merge Patch specification:
Payload
Response
Status Codes
- 204 No Content
- 400 Bad Request
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found
- 500 Internal Server Error
Headers
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
Payload
Update Report Expense Compact Schema
| Name | Type | Format | Description |
|---|---|---|---|
businessPurpose |
string |
- | The text input for the business purpose by the user. Maximum length: 64 characters |
customData |
CustomData |
- | The details from the customData fields. These fields may not have data, depending on the configuration. |
expenseSource |
string |
- | Required The source of the expense. Supported values: EA - Expense Assistant, MOB - Mobile, OTHER - Unknown, SE - Smart Expense, TA - Travel Allowance, TR - Travel Request, UI - Web UI |
CustomData
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
- | Required The unique identifier of the custom field. Examples: custom1, orgUnit1 |
isValid |
boolean |
true/false |
Whether the value returned is valid or not. This value is returned for custom fields of all data types and is specifically evaluated for list items to represent the current status. Default: true |
value |
string |
- | The value of the custom field. This field can have values for all the supported data types such as text, integer, boolean and listItemId. Maximum length: 48 characters |
Example
Request
curl --location --request PATCH 'https://us.api.concursolutions.com/expensereports/v4/reports/764428DD6A664AF0BFCB/expenses/84FCBB92BD4E5342B849DAC29FD163A1' \
--header 'Authorization: Bearer {access_token}' \
--header 'Concur-CorrelationId: Expense-Test' \
--header 'Content-Type: application/json' \
--header 'Content-Type: text/plain' \
--data-raw '{
"customData": [
{
"id": "custom09",
"value": "81188b39-605d-2d4f-b80b-43efa84a7b49",
"isValid": true
}
],
"businessPurpose":"Office Supplies",
"expenseSource":"OTHER"
}'
Response
204 No Content
Schema
ReportExpenseSummary
| Name | Type | Format | Description |
|---|---|---|---|
allocationSetId |
string |
- | The identifier of the allocation set associated with the expense. Allocations which belong to the same set were created at the same time. |
allocationState |
string |
- | Required Allocation state for the expense. Supported values: FULLY_ALLOCATED, NOT_ALLOCATED, PARTIALLY_ALLOCATED |
approvedAmount |
Amount |
- | The approved amount of the expense, in the report currency. |
approverAdjustedAmount |
Amount |
- | The total amount adjusted for the expense by the approver |
attendeeCount |
integer |
int32 |
The total number of attendees associated with the expense. |
businessPurpose |
string |
- | The text input for the business purpose by the user. |
claimedAmount |
Amount |
- | The total non-personal amount claimed for reimbursement for the expense. |
ereceiptImageId |
string |
- | The unique identifier of the eReceipt image associated with the expense. |
exchangeRate |
ExchangeRate |
- | Required Exchange rate data for the expense. |
expenseId |
string |
- | Required The unique identifier for the expense. |
expenseSourceIdentifiers |
ExpenseSourceIdentifiers |
- | The list of expense sources associated with the expense |
expenseType |
ExpenseType |
- | Required The expense type information for the expense. |
hasBlockingExceptions |
boolean |
- | Required Whether the expense has any exceptions that block it from being submitted. |
hasExceptions |
boolean |
true/false |
Required Whether the expense has any exceptions. |
hasMissingReceiptDeclaration |
boolean |
true/false |
Required Whether the expense has an affidavit declaration for missing receipt. |
imageCertificationStatus |
string |
- | The final status of the receipt image associated with the expense. |
isAutoCreated |
boolean |
true/false |
Required Whether the expense is auto-created. |
isImageRequired |
boolean |
true/false |
Required Whether the image is required for the expense. |
isPaperReceiptRequired |
boolean |
true/false |
Required Whether the paper receipt is required for the expense to be submitted. |
isPersonalExpense |
boolean |
true/false |
Required Whether the expense is marked as personal (non-reimbursable) by the user. |
jptRouteId |
string |
- | The unique route ID to identify a Japan rail route. |
links |
Link |
- | Resource links related to this call. |
location |
Location |
- | The location information of the expense. |
paymentType |
PaymentType |
- | Required The payment type information for the expense. |
postedAmount |
Amount |
- | Required The amount of the expense, in the report currency. |
receiptImageId |
string |
- | The unique identifier of the image associated with the expense. |
ticketNumber |
string |
- | The ticket number associated with the travel. |
transactionAmount |
Amount |
- | Required The amount of the expense, in the transaction currency paid to the vendor. |
transactionDate |
string |
YYYY-MM-DD |
The transaction date. |
travelAllowance |
TravelAllowance |
- | The travel allowance data associated with the expense. |
vendor |
Vendor |
- | The vendor information for the expense. |
ReportExpenseDetail
| Name | Type | Format | Description |
|---|---|---|---|
allocationSetId |
string |
- | The identifier of the allocation set associated with the expense. Allocations which belong to the same set are created at the same time. |
allocationState |
string |
- | Required Allocation state for the expense. Supported values: FULLY_ALLOCATED, NOT_ALLOCATED, PARTIALLY_ALLOCATED |
approvedAmount |
Amount |
- | The approved amount of the expense, in the report currency. |
approverAdjustedAmount |
Amount |
- | The total amount adjusted for the expense by the approver. |
attendeeCount |
integer |
int32 |
The total number of attendees associated with the expense. |
authorizationRequestExpenseId |
string |
- | The authorization request expense ID associated with the expense. |
budgetAccrualDate |
string |
YYYY-MM-DD |
The budget accrual date of the expense. |
businessPurpose |
string |
- | The text input for the business purpose by the user. |
claimedAmount |
Amount |
- | The total non-personal amount claimed for reimbursement for the expense |
customData |
CustomData |
- | The details from the customData fields. These fields may not have data, depending on the configuration. |
ereceiptImageId |
string |
- | The unique identifier of the eReceipt image associated with the expense. |
exchangeRate |
ExchangeRate |
- | Required Exchange rate data for the expense. |
expenseId |
string |
- | Required The unique identifier for the expense |
expenseSourceIdentifiers |
ExpenseSourceIdentifiers |
- | The list of expense sources associated with the expense. |
expenseTaxSummary |
ExpenseTaxSummary |
- | Tax information for the expense. |
expenseType |
ExpenseType |
- | Required The expense type information for the expense. |
hasBlockingExceptions |
boolean |
true/false |
Required Whether the expense has any exceptions that blocks it from being submitted. |
hasExceptions |
boolean |
true/false |
Required Whether the expense has any exceptions. |
hasMissingReceiptDeclaration |
boolean |
true/false |
Whether the expense has an affidavit declaration for missing receipt. |
imageCertificationStatus |
string |
- | The final status of the receipt image associated with the expense. Supported values: ACCEPTED, PROCESSED, PROCESSING, PDF, FAILED, NO_PROCESSING_REQUIRED |
isAutoCreated |
boolean |
true/false |
Required Whether the expense is auto created. |
isExcludedFromCashAdvanceByUser |
boolean |
true/false |
Required Whether the user has excluded the expense from cash advance. |
isExpenseBillable |
boolean |
true/false |
Required Whether the expense is billable. |
isExpenseRejected |
boolean |
true/false |
Required Whether the approver or processor has rejected this expense in the report. If true, then this expense will be sent back to the report submitted in an addendum (split) report. |
isImageRequired |
boolean |
true/false |
Required Whether the image is required for the expense. |
isPaperReceiptReceived |
boolean |
true/false |
Required Whether the paper receipt was received for the expense. |
isPaperReceiptRequired |
boolean |
true/false |
Required Whether the paper receipt is required for the expense to be submitted. |
isPersonalExpense |
boolean |
true/false |
Required Whether the expense is marked as personal (non-reimbursable) by the user. |
jptRouteId |
string |
- | The unique route ID to identify a Japan rail route. |
links |
Link |
- | Resource links related to this call. |
location |
Location |
- | The location information of the expense. |
merchantTaxId |
string |
- | Merchant tax ID for the expense. |
mileage |
Mileage |
- | The mileage data associated with the expense. |
parentExpenseId |
string |
- | Expense ID of the parent expense. |
paymentType |
PaymentType |
- | Required The payment type information for the expense. |
postedAmount |
Amount |
- | Required The amount of the expense, in the report currency. |
receiptImageId |
string |
- | The unique identifier of the image associated with the expense. |
receiptType |
ReceiptType |
- | Receipt type for the expense. |
taxRateLocation |
string |
- | Required Transaction location relative to the employee's home location as defined by their user profile. Supported values: FOREIGN - The expense transaction took place in foreign currency, HOME - The expense transaction took place in the reimbursement currency, OUT_OF_PROVINCE - The expense transaction took place outside the state jurisdiction. Default: HOME |
transactionAmount |
Amount |
- | Required The amount of the expense, in the transaction currency paid to the vendor. |
transactionDate |
string |
YYYY-MM-DD |
The transaction date of the expense. |
travel |
Travel |
- | The travel data associated with the expense. |
travelAllowance |
TravelAllowance |
- | The travel allowance data associated with the expense. |
vendor |
Vendor |
- | The vendor information for the expense. |
CustomData
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
- | Required The unique identifier of the custom field. Examples: custom1, orgUnit1 |
isValid |
boolean |
true/false |
Whether the value returned is valid or not. This value is returned for custom fields of all data types and is specifically evaluated for list items to represent the current status. Default: true |
value |
string |
- | The value of the custom field. This field can have values for all the supported data types such as text, integer, boolean and listItemId. Maximum length: 48 characters |
Amount
| Name | Type | Format | Description |
|---|---|---|---|
currencyCode |
string |
- | Required The 3-letter ISO 4217 currency code for the expense report currency, based on the user's assigned reimbursement currency when the report was created. Examples: USD - US dollars; BRL - Brazilian real; CAD - Canadian dollar; CHF - Swiss franc; EUR - Euro; GBO - Pound sterling; HKD - Hong Kong dollar; INR - Indian rupee; MXN - Mexican peso; NOK - Norwegian krone; SEK - Swedish krona |
value |
number |
double |
Required The amount in the defined currency. |
ExpenseSourceIdentifiers
| Name | Type | Format | Description |
|---|---|---|---|
creditCardTransactionId |
string |
- | The unique identifier of the credit card transaction (indexed transactionId) associated with the expense. |
ereceiptId |
string |
- | - |
expenseCaptureImageId |
string |
- | The unique identifier of the expense capture image associated with the expense. |
jptRouteId |
string |
- | The unique identifier to identify a Japan rail route. |
personalCardTransactionId |
string |
- | The unique identifier of the personal card transaction associated with the expense. |
quickExpenseId |
string |
- | The unique identifier of the mobile expense associated with the expense. |
segmentId |
integer |
int64 |
The unique identifier of the segment associated with the expense. |
segmentTypeId |
string |
- | Segment type ID associated with the trip. Supported values: AIRFR - Air Ticket, AIRSU - Air Subscription, CARRT - Car Rental, DININ - Dining, EVENT - Event, HOTEL - Hotel Reservation, INSUR - Insurance, LIMOF - Limousine Reservation, MISC - Miscellaneous, PARKG - Parking Fee, RAILF - Train Ticket, RAISU - Train Subscription, TAXIF - Taxi Fare, VISA - Visa |
tripId |
integer |
int64 |
The unique identifier of the trip ID associated with the expense. |
ExchangeRate
| Name | Type | Format | Description |
|---|---|---|---|
operation |
string |
- | Required Exchange rate operation. Supported values: MULTIPLY or DIVIDE |
value |
number |
double |
Required Exchange rate value. |
ExpenseTaxSummary
| Name | Type | Format | Description |
|---|---|---|---|
netAdjustedTaxAmount |
Amount |
- | Net adjusted tax amount. |
netReclaimAdjustedAmount |
Amount |
- | Net reclaim adjusted amount. |
netReclaimAmount |
Amount |
- | Net reclaim amount. |
netTaxAmount |
Amount |
- | Net tax amount. |
totalReclaimAdjustedAmount |
Amount |
- | Total reclaim adjusted amount. |
totalReclaimPostedAmount |
Amount |
- | Total reclaim posted amount. |
totalTaxAdjustedAmount |
Amount |
- | Total tax adjusted amount. |
totalTaxPostedAmount |
Amount |
- | Total tax posted amount. |
vatTaxTotal |
Amount |
- | VAT tax total amount. |
ExpenseType
| Name | Type | Format | Description |
|---|---|---|---|
code |
string |
- | The code of the expense type. |
id |
string |
- | Required The unique identifier of the expense type. Maximum length: 5 characters. Example: BRKFT |
isDeleted |
boolean |
true/false |
Whether the expense type returned is deleted or not. |
name |
string |
- | The name of the expense type (localized as per accept-language header). |
Location
| Name | Type | Format | Description |
|---|---|---|---|
city |
string |
- | The location city. |
countryCode |
string |
- | The location country ISO 3166-1 code. |
countrySubDivisionCode |
string |
- | The location country sub division ISO 3166-2 code. |
id |
string |
- | The unique identifier of the location. When location id is specified (when creating or updating a resource), other location object fields will be ignored. |
name |
string |
- | The location name (localized as per accept-language header). |
Mileage
| Name | Type | Format | Description |
|---|---|---|---|
hasCaravanAttached |
boolean |
true/false |
Whether the mileage expense has caravan or trailer attached to the car. Default: false |
hasDogIncluded |
boolean |
true/false |
Whether the mileage expense includes a dog for work purposes. Default: false |
hasForestOrConstructionSiteRoadInRoute |
boolean |
true/false |
Whether the mileage route is via a forest road or construction site road. Default: false |
hasForestRoadInRoute |
boolean |
true/false |
Whether the mileage route has forest road. Default: false |
hasMachinery |
boolean |
true/false |
Whether machines or equipment are transported in the car for this mileage expenses. Default: false |
hasMobileCanteenOrHeavyLoadAttached |
boolean |
true/false |
Whether the mileage expense has mobile canteen or is transporting a heavy load attached to the car. Default: false |
hasTrailerAttached |
boolean |
true/false |
Whether the mileage expense has trailer attached to the car. Default: false |
isMarkedAsHigherRate |
boolean |
true/false |
Whether a higher rate should be applied to the mileage expense. Default: false |
odometerEnd |
integer |
int32 |
The odometer reading at the end of the journey. |
odometerStart |
integer |
int32 |
The odometer reading at the start of the journey. |
passengerCount |
integer |
int32 |
The number of passengers in the vehicle during the journey. |
personalDistance |
integer |
int32 |
The portion of the journey attributed to personal use. Default: 0 |
routeId |
string |
- | The unique identifier of the route for this journey. |
totalDistance |
integer |
int32 |
Required The total distance for this journey. |
vehicleId |
string |
- | Required The unique identifier for the vehicle used for this journey. |
PaymentType
| Name | Type | Format | Description |
|---|---|---|---|
code |
string |
- | The code of the payment type. |
id |
string |
- | Required The unique identifier of the payment type. Maximum length: 4 characters. Example: CASH |
name |
string |
- | The name of the payment type (localized as per accept-language header). |
ReceiptType
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
- | Required The unique identifier for the receipt type. Supported values: N - No Receipt, R - Regular Receipt, T - Tax Receipt. Default value: N |
status |
string |
- | Receipt status (localized as per accept-language header). |
Travel
| Name | Type | Format | Description |
|---|---|---|---|
airlineFeeTypeCode |
string |
- | Airline fee type code. Supported values: BAGGS, BUSIN, OBENT, ONBRD, OTHER, PRACC, SEATS, TKCHG, UPGRD |
airlineFeeTypeName |
string |
- | The localized airline fee type name. |
airlineServiceClassCode |
string |
- | The airline service class code. Supported values: BUSIN, COACH, FIRST |
airlineServiceClassName |
string |
- | The localized airline service class name. |
carRentalDays |
integer |
int32 |
The number of days car was rented. Minimum value: 0 |
endLocation |
string |
- | Location where the travel ended. Maximum length: 100 characters |
hotelCheckinDate |
string |
YYYY-MM-DD |
The hotel checkin date of the expense. |
hotelCheckoutDate |
string |
YYYY-MM-DD |
The hotel checkout date of the expense. |
startLocation |
string |
- | Location where the travel started. Maximum length: 100 characters |
ticketNumber |
string |
- | The ticket number associated with the travel. Maximum length: 32 characters |
TravelAllowance
| Name | Type | Format | Description |
|---|---|---|---|
dailyLimitAmount |
number |
double |
The allowed amount based on government travel allowance rates. |
dailyTravelAllowanceId |
string |
- | The fixed daily travel allowance ID associated with the expense. Maximum length: 32 characters |
isExpensePartOfTravelAllowance |
boolean |
true/false |
Whether the expense is part of travel allowance. Default value: false |
Vendor
| Name | Type | Format | Description |
|---|---|---|---|
description |
string |
- | The description of the vendor. Maximum length: 64 characters |
id |
string |
- | The unique identifier of the vendor. |
name |
string |
- | The name of the vendor (localized as per accept-language header). |
UpdateReportExpense
| Name | Type | Format | Description |
|---|---|---|---|
approverAdjustedAmount |
Amount |
- | The total amount adjusted for the expense by the approver. |
authorizationRequestExpenseId |
string |
- | The authorization request expense ID associated with the expense. |
budgetAccrualDate |
string |
YYYY-MM-DD |
The budget accrual date. |
businessPurpose |
string |
- | The text input for the business purpose by the user. Maximum length: 64 characters |
comment |
string |
- | A comment that describes the expense. Maximum length: 2000 characters |
customData |
CustomData |
- | The details from the customData fields. These fields may not have data, depending on the configuration. |
exchangeRate |
ExchangeRate |
- | The exchange rate data for the expense. |
expenseSource |
string |
- | Required The source of the expense. Supported values: EA - Expense Assistant, MOB - Mobile, OTHER - Unknown, SE - Smart Expense, TA - Travel Allowance, TR - Travel Request, UI - Web UI |
expenseType |
ExpenseType |
- | The expense type data for the expense. |
hasMissingReceiptDeclaration |
boolean |
true/false |
Whether the expense has an affidavit declaration for missing receipt. |
isCopyDownInherited |
boolean |
true/false |
If true, any change in the report expense fields will be copied down to itemizations and allocations, as per the configuration. |
isExcludedFromCashAdvanceByUser |
boolean |
true/false |
Whether the user has excluded the expense from cash advance. |
isExpenseBillable |
boolean |
true/false |
Whether the expense is billable. |
isExpenseRejected |
boolean |
true/false |
Whether the approver or processor has rejected this expense in the report. If true, then this expense will be sent back to the report submitted in an addendum (split) report. |
isPaperReceiptReceived |
boolean |
true/false |
Whether paper receipts have been received for the expense. |
isPersonalExpense |
boolean |
true/false |
Whether the expense is marked as personal (non-reimbursable) by the user. |
jptRouteId |
string |
- | The unique route ID to identify a Japan rail route. |
location |
Location |
- | The location data of the expense. |
merchantTaxId |
string |
- | The merchant tax ID for the expense. Maximum length: 64 characters |
mileage |
Mileage |
- | The mileage data associated with the expense. |
paymentType |
PaymentType |
- | The payment type data for the expense. Default: CASH |
receiptImageId |
string |
- | The unique identifier of the image associated with the expense. |
receiptType |
ReceiptType |
- | Receipt type for the expense. |
smartExpense |
SmartExpense |
- | The smart expense data associated with this expense. |
tax |
Tax |
- | The tax data associated with the expense. |
taxRateLocation |
string |
- | Transaction location relative to the employee's home location as defined by their user profile. Supported values: FOREIGN - The expense transaction took place in foreign currency, HOME - The expense transaction took place in the reimbursement currency, OUT_OF_PROVINCE - The expense transaction took place outside the state jurisdiction |
transactionAmount |
Amount |
- | The amount of the expense, in the transaction currency paid to the vendor. |
transactionDate |
string |
YYYY-MM-DD |
The transaction date (ISO-8601) of the expense. |
travel |
Travel |
- | The travel data associated with the expense. |
travelAllowance |
TravelAllowance |
- | The travel allowance data associated with the expense. |
vendor |
Vendor |
- | The vendor data for the expense. |
SmartExpense
| Name | Type | Format | Description |
|---|---|---|---|
creditCardTransactionId |
string |
- | The unique identifier of the credit card transaction (indexed transactionId) associated with the expense. |
ereceipt |
EReceipt |
- | EReceipt information for the expense. |
expenseAttendees |
ExpenseAttendees |
- | The attendee details associated with the smart expense. |
isAutoCreated |
boolean |
true/false |
Whether this expense is auto-created. This element only applies to POST expense request. Default: false |
personalCardTransactionId |
string |
- | The unique identifier of the personal card transaction associated with the expense. |
quickExpenseId |
string |
- | The unique identifier of the mobile expense associated with the expense. When quickExpenseId is specified, the exchangeRate.value field value will be ignored and its value will be read from exchange rate currency service. exchangeRate.operation will still be honored. |
trip |
Trip |
- | Trip data associated with the expense. |
Tax
| Name | Type | Format | Description |
|---|---|---|---|
expenseTax1 |
ExpenseTax |
- | Required The tax data for the expense. |
expenseTax2 |
ExpenseTax |
- | The tax data for the expense. |
ExpenseTax
| Name | Type | Format | Description |
|---|---|---|---|
customData |
CustomData | - | The details from the customData fields. These fields may not have data, depending on the configuration. |
reclaimCode |
string |
- | The tax reclaim code. Maximum length: 20 characters |
reclaimTransactionAmount |
number |
double |
The tax reclaim transaction amount. |
taxAuthorityId |
string |
- | Required The unique identifier of the tax authority. |
taxAuthorityName |
string |
- | The name of the tax authority. |
taxCode |
string |
- | The tax code. Maximum length: 20 characters |
taxFormId |
string |
- | The unique identifier of the tax form associated with the expense. |
taxLabel |
string |
- | The localized label of the tax authority. |
taxRateTypeId |
string |
- | The unique identifier of the tax rate type ID. |
taxRateTypeName |
string |
- | The name of the tax rate type. |
taxReclaimConfigurationId |
string |
- | The unique identifier of the tax reclaim configuration ID. |
taxTransactionAmount |
number |
double |
The tax transaction amount. |
EReceipt
| Name | Type | Format | Description |
|---|---|---|---|
carEReceipt |
CarEReceipt |
- | The eReceipt car data. |
hotelEReceipt |
HotelEReceipt |
- | The eReceipt hotel data. |
id |
string |
- | Required The unique identifier of the eReceipt with the expense. |
imageId |
string |
- | The unique identifier of the eReceipt image associated with the expense. |
templateURL |
string |
- | The URL of the eReceipt template. Maximum length: 512 characters |
type |
string |
- | Required The type of eReceipt associated with the expense. Supported values: AIR, CAR, GASXX, GENERAL, GRTRN, HOTEL, JPT, MEALS, OFFIC, PRKNG, RAIL, RIDE, SHIPG, TELEC |
HotelEReceipt
| Name | Type | Format | Description |
|---|---|---|---|
calculatedDailyRate |
number |
double |
The calculated hotel daily rate. |
endDate |
string |
YYYY-MM-DD |
The hotel checkout date. |
locationId |
string |
- | The unique identifier of the location for this hotel. |
startDate |
string |
YYYY-MM-DD |
The hotel check-in date. |
totalAmountPaid |
Amount |
- | The total amount paid. |
vendorName |
string |
- | The name of the hotel vendor. Maximum length: 255 characters. Examples: Hilton, Four Points by Sheraton, Seattle |
CarEReceipt
| Name | Type | Format | Description |
|---|---|---|---|
calculatedDailyRate |
number |
double |
The calculated car rental daily rate. |
carClass |
string |
- | The car class. Maximum length: 4 characters. Examples: IDAD, ECMZ, PCAV, IGDV |
currencyCode |
string |
- | The 3-letter ISO 4217 currency code. Examples: USD - US dollars, BRL - Brazilian real, CAD - Canadian dollar |
endDate |
string |
YYYY-MM-DD |
The car rental end date. |
fuelServiceCharge |
number |
double |
The fuel service charge. Minimum value: 0 |
numberOfRentalDays |
integer |
int32 |
The number of car rental calculated days. Minimum value: 0 |
startDate |
string |
YYYY-MM-DD |
The car rental start date. |
unitsDriven |
integer |
int32 |
The total units driven. Minimum value: 0 |
vendorName |
string |
- | The name of the car vendor. Maximum length: 255 characters. Example: ABC Rent A Car |
ExpenseAttendee
| Name | Type | Format | Description |
|---|---|---|---|
associatedAttendeeCount |
integer |
int32 |
The count of total attendees. A count greater than one (1) means there are unnamed attendees associated with this expense-attendee record. Default : 1 |
attendeeId |
string |
- | Required The unique identifier of the associated expense attendee within SAP Concur solutions. |
customData |
CustomData |
- | The details from the customData fields. These fields may not have data, depending on the configuration. |
isAmountUserEdited |
boolean |
true/false |
This field indicates if the amount value for the attendee on this expense was ever manually edited by the end user. Default: false |
isTraveling |
boolean |
true/false |
Whether the attendee was traveling when the expense was incurred. Used for FBT tax calculations. |
transactionAmount |
number |
double |
The portion of the expense transaction amount assigned to this attendee for both individual expense tracking and attendee totals across time periods. |
versionNumber |
integer |
int32 |
The version number of the attendee. This field value may always be one (1), depending on the configuration. Default: 1 |
ExpenseAttendees
| Name | Type | Format | Description |
|---|---|---|---|
expenseAttendeeList |
ExpenseAttendee |
- | The list of attendees associated with the expense. Maximum attendees: 500 |
noShowAttendeeCount |
integer |
int32 |
The number of attendees that were planned but did not show up. Default value: 0 |
Trip
| Name | Type | Format | Description |
|---|---|---|---|
airTrip |
AirTrip |
- | Air trip data associated with the expense. |
bookingOrigin |
string |
- | Booking origin of the trip. Supported values: AETM - Amadeus E-Travel, CLIQ - Concur Travel, PANM - Open Booking, TRPT - TripIt, TSUP - Travel Supplier |
bookingSource |
string |
- | Booking source of the trip. Maximum length: 48 characters. Examples: Expedia, Travelocity, Manual |
carTrip |
CarTrip |
- | Car trip data associated with the expense. |
cliqbookPaymentId |
integer |
int32 |
Cliqbook payment ID associated with the trip. |
cliqbookPaymentMethod |
string |
- | Cliqbook payment method associated with the trip. Supported values: GHOST_CARD or FLGHT_PASS |
hotelTrip |
HotelTrip |
- | Hotel trip data associated with the expense. |
merchantCode |
string |
- | Merchant code associated with the trip. Maximum length: 4 characters |
rideTrip |
RideTrip |
- | Ride or taxi trip data associated with the expense. |
segmentId |
integer |
int64 |
Required The unique identifier of the segment associated with the expense. |
segmentTypeId |
string |
- | Required Segment type ID associated with the trip. Supported values: AIRFR - Air Ticket, AIRSU - Air Subscription, CARRT - Car Rental, DININ - Dining, EVENT - Event, HOTEL - Hotel Reservation, INSUR - Insurance, LIMOF - Limousine Reservation, MISC - Miscellaneous, PARKG - Parking Fee, RAILF - Train Ticket, RAISU - Train Subscription, TAXIF - Taxi Fare, VISA - Visa |
startLocationId |
string |
- | The unique identifier of the start location associated with the trip. |
tripId |
integer |
int64 |
Required The unique identifier of the trip ID associated with the expense. |
HotelTrip
| Name | Type | Format | Description |
|---|---|---|---|
calculatedDailyRate |
number |
double |
The calculated hotel daily rate. |
endDate |
string |
YYYY-MM-DD |
The hotel checkout date. |
numberOfNights |
integer |
int32 |
The number of nights. Minimum value: 1 |
numberOfRooms |
integer |
int32 |
The number of hotel rooms. Minimum value: 1 |
startDate |
string |
YYYY-MM-DD |
The hotel check-in date. |
totalAmountPaid |
Amount |
- | The total amount paid. |
vendorName |
string |
- | The name of the hotel vendor. Maximum length: 255 characters. Examples: Hilton, Four Points by Sheraton, Seattle |
AirTrip
| Name | Type | Format | Description |
|---|---|---|---|
airlineName |
string |
- | The name of the airline vendor. Maximum length: 255 characters. Example: Alaska Airlines |
endDate |
string |
YYYY-MM-DD |
The last travel date or the travel end date. |
numberOfTravelDays |
integer |
int32 |
The number of days of travel. Minimum value: 1 |
startDate |
string |
YYYY-MM-DD |
The first travel date or the travel start date. |
ticketType |
string |
- | The airline class of service. Maximum length: 10 characters. Example: Economy |
totalAmountPaid |
Amount |
- | The total amount paid. |
RideTrip
| Name | Type | Format | Description |
|---|---|---|---|
startDate |
string |
YYYY-MM-DD |
The start date for the ride. |
totalAmountPaid |
Amount |
- | The total amount paid. |
vendorName |
string |
- | The name of the vendor. Maximum length: 255 characters. Example: Yellow Cab |
CarTrip
| Name | Type | Format | Description |
|---|---|---|---|
calculatedDailyRate |
number |
double |
The calculated car rental daily rate. |
carClass |
string |
- | The car class. Maximum length: 10 characters. Examples: IDAD, ECMZ, PCAV, IGDV |
endDate |
string |
YYYY-MM-DD |
The car rental end date. |
numberOfCars |
integer |
int32 |
The number of cars rented. Minimum value: 1 |
numberOfRentalDays |
integer |
int32 |
The number of car rental calculated days. Minimum value: 0 |
startDate |
string |
YYYY-MM-DD |
The car rental start date. |
totalAmountPaid |
Amount |
- | The total amount paid. |
vendorName |
string |
- | The name of the car vendor. Maximum length: 255 characters. Example: ABC Rent A Car |
Link
| Name | Type | Format | Description |
|---|---|---|---|
deprecation |
string |
- | - |
href |
string |
- | Required The URL of the related HATEOAS link that you can use for subsequent calls. |
hreflang |
string |
- | - |
isTemplated |
boolean |
true/false |
Required Whether the href is parameterized. |
media |
string |
- | - |
method |
string |
- | Required The HTTP method required for the related call. |
rel |
string |
- | Required The link relationship that describes how the href relates to the API call. |
title |
string |
- | - |
type |
string |
- | - |
ErrorMessage
| Name | Type | Format | Description |
|---|---|---|---|
errorId |
string |
- | The unique identifier of the error associated with the response. |
errorMessage |
string |
- | Required The detailed error message. |
httpStatus |
string |
- | Required The http response code and phrase for the response. |
path |
string |
- | Required The URI of the attempted request. |
timestamp |
string |
date-time |
Required The time when the error was captured. |
validationErrors |
ValidationError |
- | The validation error messages. |
ValidationError
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
- | The ID of the validation error. |
message |
string |
- | The detailed message of the validation error. |
source |
string |
- | The type of validation which failed. |
Reports v4
The Reports v4 API can be used to read and modify an expense report header of an existing expense report. This API can be used to change attributes like report name, business purpose, etc.
Limitations: This API is only available to partners who have been granted access by SAP Concur. Access to this documentation does not provide access to the API.
- Prior Versions
- Products and Editions
- Scope Usage
- Dependencies
- Access Token Usage
- Retrieve a Report by ID
- Update a Report
- Approve or Send Back a Report
- Schema
- Error
- Validation Errors
Prior Versions
- Report Header v1 (Deprecated) documentation is available here
- Reports v3 documentation is available here
Products and Editions
- Concur Expense Professional Edition
- Concur Expense Standard Edition
Scope Usage
Required Scopes:
| Name | Description | Endpoint |
|---|---|---|
expense.report.read |
Get information about expense reports. | GET |
expense.report.readwrite |
Read and write expense report headers. | PATCH |
expense.report.workflowstatus.write |
Approve or Send Back the Report in the workflow | PATCH |
user.read |
Get User Information, necessary for userID. |
GET |
Optional Scope:
| Name | Description | Endpoint |
|---|---|---|
spend.listitem.read |
Read only access to spend list items listItemId. |
GET |
spend.list.read |
Read only access to spend list and category details. | GET |
Dependencies
SAP Concur clients must purchase Concur Expense in order to use this API. This API requires the Identity v4 API which is currently only available to approved early access partners. Please contact your SAP Concur representative for more information.
Access Token Usage
This API supports both company level and user level access tokens.
Retrieve a Report by ID
Retrieves the details of the specific report header.
Scopes
expense.report.read - Refer to Scope Usage for full details.
Request
URI Template
https://{datacenterURI}/expensereports/v4/users/{userID}/context/{contextType}/reports/{reportId}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
userID |
string |
- | Required The unique identifier of the SAP Concur user. Use Identity v4 API to retrieve the userID. |
contextType |
string |
- | Required The access level of the SAP Concur user, which determines the form fields they can view/modify. Supported values: TRAVELER, PROXY |
reportId |
string | - | Required The unique identifier of the report that is being read. |
Headers
- RFC 7231 Accept-Language
- RFC 7231 Content-Type
- RFC 7231 Content-Encoding
- RFC 7234 Cache-Control
- RFC 7232 If-Modified-Since
- RFC 7231 Accept-Encoding
- RFC 7235 Authorization - Bearer Token that identifies the caller. This is the Company or User access token.
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
Response
Status Codes
Headers
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
Payload
Example
Request
curl --location --request GET 'https://us.api.concursolutions.com/expensereports/v4/users/32C2FCC3-B2E8-4907-9672-5B3F49B1C643/context/TRAVELER/reports/764428DD6A664AF0BFCB' \
--header 'Authorization: Bearer {access_token}' \
--header 'Concur-CorrelationId: Expense-Report-test' \
--header 'Content-Type: application/json'
Response
200 OK
{
"approvalStatus": "Not Submitted",
"approvalStatusId": "A_NOTF",
"concurAuditStatus": "NOTR",
"customData": [
{
"id": "custom15",
"value": "4366A89A916F074099A971B000989A94",
"isValid": true,
"listItemUrl": "https://us.api.concursolutions.com/list/v4/items?id=4366A89A916F074099A971B000989A94"
},
{
"id": "custom16",
"value": "Test33224ASDF",
"isValid": true,
"listItemUrl": null
},
{
"id": "custom3",
"value": "582AE31D0F506C4BAA97573F2A90F03B",
"isValid": true,
"listItemUrl": "https://us.api.concursolutions.com/list/v4/items?id=582AE31D0F506C4BAA97573F2A90F03B"
},
{
"id": "custom4",
"value": "79AE45D0F6757946AC2B01CDFA6CA326",
"isValid": true,
"listItemUrl": "https://us.api.concursolutions.com/list/v4/items?id=79AE45D0F6757946AC2B01CDFA6CA326"
}
],
"ledger": "DEFAULT",
"ledgerId": "2703E3FBD393DA4484ED3CB07303407C",
"paymentStatus": "Not Paid",
"paymentStatusId": "P_NOTP",
"submitDate": null,
"approvedAmount": {
"value": 525.00000000,
"currencyCode": "USD"
},
"claimedAmount": {
"value": 525.00000000,
"currencyCode": "USD"
},
"amountCompanyPaid": {
"value": 0E-8,
"currencyCode": "USD"
},
"paymentConfirmedAmount": {
"value": 0E-8,
"currencyCode": "USD"
},
"amountDueCompany": {
"value": 0E-8,
"currencyCode": "USD"
},
"amountDueCompanyCard": {
"value": 0E-8,
"currencyCode": "USD"
},
"amountDueEmployee": {
"value": 0E-8,
"currencyCode": "USD"
},
"personalAmount": {
"value": 0E-8,
"currencyCode": "USD"
},
"reportTotal": {
"value": 525.00000000,
"currencyCode": "USD"
},
"amountNotApproved": {
"value": 0E-8,
"currencyCode": "USD"
},
"isFinancialIntegrationEnabled": false,
"canReopen": false,
"isReopened": false,
"isReceiptImageAvailable": false,
"isReceiptImageRequired": true,
"isPaperReceiptsReceived": false,
"reportId": "764428DD6A664AF0BFCB",
"currency": "US, Dollar",
"currencyCode": "USD",
"analyticsGroupId": "C8CB395275EC4FE9AF6CD5B535EA2B17",
"hierarchyNodeId": "0F941E0B0A2C974EB2B06CDA67973052",
"allocationFormId": "FD7E9C6389EF495B85042319D58CAE53",
"links": [
{
"rel": "self",
"href": "https://us.api.concursolutions.com/expensereports/v4/users/32C2FCC3-B2E8-4907-9672-5B3F49B1C643/context/TRAVELER/reports/764428DD6A664AF0BFCB",
"hreflang": null,
"media": null,
"title": null,
"type": null,
"deprecation": null,
"method": "GET",
"isTemplated": false
}
],
"reportDate": "2020-03-25",
"reportFormId": "674B67F0C6BD4E9CA5D91AFB82CC8ABB",
"businessPurpose": "Facility cleaning and renovation",
"countryCode": "US",
"countrySubDivisionCode": "US-WA",
"policyId": "EE095F66AEF52B4A9CE62952601E5CB1",
"startDate": "2020-03-10",
"endDate": "2020-03-14",
"name": "March Expenses",
"policy": "JH - US Expense Policy",
"country": "UNITED STATES",
"userId": "32c2fcc3-b2e8-4907-9672-5b3f49b1c643",
"reportType": "Regular",
"redirectFund": null,
"creationDate": "2020-03-25T20:42:39Z",
"canRecall": false,
"reportVersion": 0
}
Update a Specific Report
Updates the attributes of a specific report.
Scopes
expense.report.readwrite - Refer to Scope Usage for full details.
Request
URI Template
https://{datacenterURI}/expensereports/v4/users/{userID}/context/{contextType}/reports/{reportId}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
userID |
string |
- | Required The unique identifier of the SAP Concur user. Use Identity v4 API to retrieve the userID. |
contextType |
string |
- | Required The access level of the SAP Concur user, which determines the form fields they can view/modify. Supported values: TRAVELER, PROXY |
reportId |
string | - | Required The unique identifier of the report that is being modified. |
Headers
- RFC 7231 Accept-Language
- RFC 7231 Content-Type
- RFC 7231 Content-Encoding
- RFC 7234 Cache-Control
- RFC 7232 If-Modified-Since
- RFC 7231 Accept-Encoding
- RFC 7235 Authorization - Bearer Token that identifies the caller. This is the Company or User access token.
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
REST Design Specification
PATCH operations in Expense Reports v4 conform to the JSON Merge Patch specification:
Payload
Response
Status Codes
- 204 No Content
- 400 Bad Request
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found
- 500 Internal Server Error
Headers
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
Payload
Example
Request
curl --location --request PATCH 'https://us.api.concursolutions.com/expensereports/v4/users/32C2FCC3-B2E8-4907-9672-5B3F49B1C643/context/TRAVELER/reports/764428DD6A664AF0BFCB' \
--header 'Authorization: Bearer {access_token}' \
--header 'Concur-CorrelationId: Viswa test' \
--header 'Content-Type: application/json' \
--data-raw '{
"customData": [
{
"id": "custom15",
"value": "E31CB42509F9FF408BA7DD6713AB49BD",
"isValid": true
}
],
"businessPurpose":"Office Facility Supplies",
"reportSource":"OTHER"
}'
Response
204 No Content
Approve or Send Back a Report
The Approve function advances the specified report to the next step if it is in a system step. The Send Back function sends back the specified report to report owner .
Scopes
expense.report.workflowstatus.write - Refer to Scope Usage for full details.
Request
URI Template
https://{datacenterURI}/expensereports/v4/reports/{reportId}/approve
https://{datacenterURI}/expensereports/v4/reports/{reportId}/sendBack
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
reportId |
string | - | Required The unique identifier of the report that is being approved or sent back. |
Headers
- RFC 7231 Accept-Language
- RFC 7231 Content-Type
- RFC 7231 Content-Encoding
- RFC 7234 Cache-Control
- RFC 7232 If-Modified-Since
- RFC 7231 Accept-Encoding
- RFC 7235 Authorization - Bearer Token that identifies the caller. This is the Company or User access token.
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
REST Design Specification
PATCH operations in Expense Reports v4 conform to the JSON Merge Patch specification:
Payload
Response
Status Codes
- 204 No Content
- 400 Bad Request
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found
- 500 Internal Server Error
Headers
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
Payload
Example
Request
curl --location --request PATCH 'https://us.api.concursolutions.com/expensereports/reports/764428DD6A664AF0BFCB/Approve' \
--header 'Authorization: Bearer {access_token}' \
--header 'Concur-CorrelationId: Viswa test' \
--header 'Content-Type: application/json' \
--data-raw '{
"reportSource":"OTHER"
}'
Response
204 No Content
Schema
ReportDetails
| Name | Type | Format | Description |
|---|---|---|---|
allocationFormId |
string |
- | The unique identifier of the allocation form. |
amountCompanyPaid |
Amount |
- | Required The amount paid by the company. |
amountDueCompany |
Amount |
- | Required The amount that the employee owes the company. |
amountDueCompanyCard |
Amount |
- | Required The amount that the employee/company owes the corporate card. |
amountDueEmployee |
Amount |
- | Required The amount that the company owes the employee. |
amountNotApproved |
Amount |
- | Required The amount that was not approved for the report. |
analyticsGroupId |
string |
- | Required The unique identifier of the business intelligence hierarchy node. |
approvalStatus |
string |
- | Required The report’s approval status, in the user’s language. |
approvalStatusId |
string |
- | Required The unique identifier of the approval status. |
approvedAmount |
Amount |
- | Required The total amount of approved expenses in the report. |
businessPurpose |
string |
- | The text input for the business purpose by the user. |
canRecall |
boolean |
true/false |
Required Whether the report can be recalled by the current user. |
canReopen |
boolean |
true/false |
Whether the report can be reopened after payment. |
cardProgramStatementPeriodId |
string |
- | The unique identifier of card program statement period on the report. |
claimedAmount |
Amount |
- | Required The total amount of all non-personal expenses in the report. |
concurAuditStatus |
string |
- | Required The status of audit for the report. |
country |
string |
- | The country name associated with the report (localized as per accept-language header). |
countryCode |
string |
ISO 3166-1 alpha-2 country code |
The report country. Maximum characters: 2. Example: US - United States |
countrySubDivisionCode |
string |
- | The location country sub division ISO 3166-2 code. |
creationDate |
string |
YYYY-MM-DDTHH:mm:ssZ |
Required The UTC datetime when the user created the report. |
currency |
string |
- | Required The currency name for the report (localized as per accept-language header). |
currencyCode |
string |
- | Required The 3-letter ISO 4217 currency code for the expense report currency. Examples: USD - US dollars; BRL - Brazilian real; CAD - Canadian dollar; CHF - Swiss franc; EUR - Euro; GBO - Pound sterling; HKD - Hong Kong |
customData |
CustomData |
- | The details from the customData fields. These fields may not have data, depending on the configuration. |
endDate |
string |
YYYY-MM-DD |
The end date (ISO-8601) of the report as used for trip-based reporting. |
hierarchyNodeId |
string |
- | Required The unique identifier of the group hierarchy node for the report resource. |
isFinancialIntegrationEnabled |
boolean |
true/false |
Required Whether the Financial Integration setting has been enabled for this report. |
isPaperReceiptsReceived |
boolean |
true/false |
Required Whether paper receipts have been received for the report. |
isReceiptImageAvailable |
boolean |
true/false |
Required Whether the receipt image is available at the report level. |
isReceiptImageRequired |
boolean |
true/false |
Required Whether the receipt image is required at the report level. |
isReopened |
boolean |
true/false |
Whether the report is reopened. |
ledger |
string |
- | Required The ledger name to which the report belongs (localized as per accept-language header). |
ledgerId |
string |
- | Required The unique identifier of the ledger. |
links |
Link |
- | Resource links related to this call. |
name |
string |
- | Required The expense report name input by the user. |
paymentConfirmedAmount |
Amount |
- | Required The amount that was paid on the report. |
paymentStatus |
string |
- | Required The report's payment status in the user's language. |
paymentStatusId |
string |
- | Required The unique identifier of the payment status of the report. |
personalAmount |
Amount |
- | Required The total amount of expenses marked as personal on the report. |
policy |
string |
- | Required The policy name to which the report adheres (localized as per accept-language header). |
policyId |
string |
- | Required The unique identifier of the policy that applies to this report. |
redirectFund |
RedirectFund |
- | Funds redirected to IBCP card. |
reportDate |
string |
YYYY-MM-DD |
The date assigned to the report by the user. |
reportFormId |
string |
- | Required The unique identifier of the report form. |
reportId |
string |
- | Required The unique identifier for the report resource. |
reportNumber |
string |
- | User friendly unique identifier for the report. |
reportTotal |
Amount |
- | Required The total amount on the report. |
reportType |
string |
- | This value identifies the method used to create the report. Statement refers to company billed statement reports and auto-created refers to reports created by Expense Assistant. |
reportVersion |
integer |
int32 |
Required The current version of the report. |
startDate |
string |
YYYY-MM-DD |
The start date of the report as used for trip-based reporting. |
submitDate |
string |
YYYY-MM-DDTHH:mm:ssZ |
The UTC datetime when the user submitted the report. |
submitterId |
string |
- | The unique identifier of the employee who submitted the report. |
taxConfigId |
string |
- | The The tax config ID of the report. |
userId |
string |
- | Required The unique identifier of the Concur user who is the report owner. |
UpdateReport
| Name | Type | Format | Description |
|---|---|---|---|
businessPurpose |
string |
- | The text input for the business purpose by the user. |
comment |
string |
- | The expense report comment added by the user. |
country |
string |
- | The country name associated with the report (localized as per accept-language header). |
countryCode |
string |
- | The location country ISO 3166-1 code. |
countrySubDivisionCode |
string |
- | The location country sub division ISO 3166-2 code. |
customData |
CustomData |
- | The details from the customData fields. These fields may not have data, depending on the configuration. |
endDate |
string |
YYYY-MM-DD |
The end date of the report as used for trip-based reporting. |
isCopyDownInherited |
boolean |
true/false |
If true, any change in the report header fields will be copied down to expenses, itemizations and allocations, as per the configuration. Usage of this flag should be deliberate as data corruption could result. |
isPaperReceiptsReceived |
boolean |
true/false |
Whether paper receipts have been received for the report. |
name |
string |
- | The expense report name input by the user. |
policy |
string |
- | The policy name to which the report adheres to. |
policyId |
string |
- | The unique identifier of the policy that applies to this report. |
redirectFund |
RedirectFund |
- | Funds redirected to IBCP card. |
reportDate |
string |
YYYY-MM-DD |
The date assigned to the report by the user. |
reportSource |
string |
- | Required The source of the report. Supported values: EA - Expense Assistant, MOB - Mobile, OTHER - Unknown, SE - Smart Expense, TR - Travel Request, UI - Web UI |
startDate |
string |
YYYY-MM-DD |
The start date of the report as used for trip-based reporting. |
CustomData
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
- | Required The unique identifier of the custom field. Examples: custom1, orgUnit1 |
isValid |
boolean |
true/false |
Whether the value returned is valid or not. This value is returned for custom fields of all data types and is specifically evaluated for list items to represent the current status. Default: true |
value |
string |
- | The value of the custom field. This field can have values for all the supported data types such as text, integer, boolean and listItemId. Maximum length: 48 characters |
Amount
| Name | Type | Format | Description |
|---|---|---|---|
currencyCode |
string |
- | Required The 3-letter ISO 4217 currency code for the expense report currency, based on the user's assigned reimbursement currency when the report was created. Examples: USD - US dollars; BRL - Brazilian real; CAD - Canadian dollar; CHF - Swiss franc; EUR - Euro; GBO - Pound sterling; HKD - Hong Kong dollar; INR - Indian rupee; MXN - Mexican peso; NOK - Norwegian krone; SEK - Swedish krona |
value |
number |
double |
Required The amount in the defined currency. |
RedirectFund
| Name | Type | Format | Description |
|---|---|---|---|
amount |
Amount |
- | Required The value of funds redirected to the IBCP card account. |
creditCardId |
string |
- | Required The unique identifier of the IBCP card account to which funds need to be redirected. |
ReportSendBackRequest
| Name | Type | Format | Description |
|---|---|---|---|
comment |
string |
- | Required Comments for sending back the report. |
currentProcessInstanceId |
string |
- | Current workflow process instance ID for validation. |
currentSequence |
integer |
int32 |
Current workflow process sequence number for validation. |
reasonCodeId |
string |
- | The unique identifier of the Reason Code only by processor. |
reportSource |
string |
- | The source of the report. Supported values: EA - Expense Assistant, MOB - Mobile, OTHER - Unknown, SE - Smart Expense, TR - Travel Request, UI - Web UI |
ReportApproveRequest
| Name | Type | Format | Description |
|---|---|---|---|
comment |
string |
- | Approver comments. |
currentProcessInstanceId |
string |
- | Current workflow process instance ID for validation. |
currentSequence |
integer |
int32 |
Current workflow process sequence number for validation. |
reportSource |
string |
- | The source of the report. Supported values: EA - Expense Assistant, MOB - Mobile, OTHER - Unknown, SE - Smart Expense, TR - Travel Request, UI - Web UI |
statusId |
string |
- | Status that will be assigned to the report by this workflow transition. |
Link
| Name | Type | Format | Description |
|---|---|---|---|
deprecation |
string |
- | - |
href |
string |
- | Required The URL of the related HATEOAS link that you can use for subsequent calls. |
hreflang |
string |
- | - |
isTemplated |
boolean |
true/false |
Required Whether the href is parameterized. |
media |
string |
- | - |
method |
string |
- | Required The HTTP method required for the related call. |
rel |
string |
- | Required The link relationship that describes how the href relates to the API call. |
title |
string |
- | - |
type |
string |
- | - |
ErrorMessage
| Name | Type | Format | Description |
|---|---|---|---|
errorId |
string |
- | The unique identifier of the error associated with the response. |
errorMessage |
string |
- | Required The detailed error message. |
httpStatus |
string |
- | Required The http response code and phrase for the response. |
path |
string |
- | Required The URI of the attempted request. |
timestamp |
string |
date-time |
Required The time when the error was captured. |
validationErrors |
ValidationError |
- | The validation error messages. |
ValidationError
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
- | The ID of the validation error. |
message |
string |
- | The detailed message of the validation error. |
source |
string |
- | The type of validation which failed. |
Workflows v4
Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.
The Workflows v4 API is used to Approve or Send Back an expense report that is in the workflow. This API is used only for normal approval steps and not for Cost Object Approval steps.
Limitations: This API is only available to partners who have been granted access by SAP Concur. Access to this documentation does not provide access to the API.
- Prior Versions
- Products and Editions
- Scope Usage
- Dependencies
- Access Token Usage
- Approve or Send Back a Report
- Schema
- Validation Errors
Prior Versions
- Report Workflow Action v1.1 documentation is available here.
Products and Editions
- Concur Expense Professional Edition
- Concur Expense Standard Edition
Scope Usage
Required Scope:
| Name | Description | Endpoint |
|---|---|---|
expense.report.workflowstatus.write |
Approve or Send Back the Report in the workflow | PATCH |
Optional Scope:
| Name | Description | Endpoint |
|---|---|---|
expense.report.read |
Get information about expense reports. | GET |
expense.report.readwrite |
Read and write expense report headers. | PATCH |
spend.listitem.read |
Read only access to spend list items listItemId. |
GET |
spend.list.read |
Read only access to spend list and category details. | GET |
user.read |
Get User Information, necessary for userID. |
GET |
Dependencies
SAP Concur clients must purchase Concur Expense in order to use this API. This API requires the Identity v4 API which is currently only available to approved early access partners. Please contact your SAP Concur representative for more information.
Access Token Usage
This API supports both company level and user level access tokens.
Approve or Send Back a Report
The Approve function advances the specified report to the next step if it is in a system step. The Send Back function sends back the specified report to report owner.
Scopes
expense.report.workflowstatus.write - Refer to Scope Usage for full details.
Request
URI Template
https://{datacenterURI}/expensereports/v4/reports/{reportId}/approve
https://{datacenterURI}/expensereports/v4/reports/{reportId}/sendBack
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
reportId |
string | - | Required The unique identifier of the report that is being approved or sent back. |
Headers
- RFC 7231 Accept-Language
- RFC 7231 Content-Type
- RFC 7231 Content-Encoding
- RFC 7234 Cache-Control
- RFC 7232 If-Modified-Since
- RFC 7231 Accept-Encoding
- RFC 7235 Authorization - Bearer Token that identifies the caller. This is the Company or User access token.
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
REST Design Specification
PATCH operations in Expense Reports v4 conform to the JSON Merge Patch specification:
Payload
Response
Status Codes
- 204 No Content
- 400 Bad Request
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found
- 500 Internal Server Error
Headers
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
Payload
Example
Request
curl --location --request PATCH 'https://us.api.concursolutions.com/expensereports/reports/764428DD6A664AF0BFCB/Approve' \
--header 'Authorization: Bearer {access_token}' \
--header 'Concur-CorrelationId: Viswa test' \
--header 'Content-Type: application/json' \
--data-raw '{
"reportSource":"OTHER"
}'
Response
204 No Content
Schema
ReportSendBackRequest
| Name | Type | Format | Description |
|---|---|---|---|
comment |
string |
- | Required Comments for sending back the report. |
currentProcessInstanceId |
string |
- | Current workflow process instance ID for validation. |
currentSequence |
integer |
int32 |
Current workflow process sequence number for validation. |
reasonCodeId |
string |
- | The unique identifier of the Reason Code only by processor. |
reportSource |
string |
- | The source of the report. Supported values: EA - Expense Assistant, MOB - Mobile, OTHER - Unknown, SE - Smart Expense, TR - Travel Request, UI - Web UI |
ReportApproveRequest
| Name | Type | Format | Description |
|---|---|---|---|
comment |
string |
- | Approver comments. |
currentProcessInstanceId |
string |
- | Current workflow process instance ID for validation. |
currentSequence |
integer |
int32 |
Current workflow process sequence number for validation. |
reportSource |
string |
- | The source of the report. Supported values: EA - Expense Assistant, MOB - Mobile, OTHER - Unknown, SE - Smart Expense, TR - Travel Request, UI - Web UI |
statusId |
string |
- | Status that will be assigned to the report by this workflow transition. |
Error
| Name | Type | Format | Description |
|---|---|---|---|
errorId |
string |
- | The unique identifier of the error associated with the response. |
errorMessage |
string |
- | Required The detailed error message. |
httpStatus |
string |
- | Required The http response code and phrase for the response. |
path |
string |
- | Required The URI of the attempted request. |
timestamp |
string |
date-time |
Required The time when the error was captured. |
validationErrors |
ValidationError |
- | The validation error messages. |
ValidationError
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
- | The ID of the validation error. |
message |
string |
- | The detailed message of the validation error. |
source |
string |
- | The type of validation which failed. |
Quick Expense v4
The Quick Expense API can be used to create an expense with basic information such as date, amount, and expense type, with or without a receipt image. This expense can be added to an expense report within Concur Expense, allowing the user to provide additional details such as attendees, itemizations etc.
Limitations: This API is only available to partners who have been granted access by SAP Concur. Access to this documentation does not provide access to the API. This API is not available in Implementation environments.
- Products and Editions
- Scope Usage
- Dependencies
- Access Token Usage
- Create a Quick Expense
- Create a Quick Expense with an Image
- Schema
Products and Editions
- Concur Expense Professional Edition
- Concur Expense Standard Edition
Scope Usage
Required Scopes:
| Name | Description | Endpoint |
|---|---|---|
quickexpense.writeonly |
Write quick expense. | POST |
user.read |
Get User Information, necessary for userID. |
POST |
receipts.writeonly |
Required if e-Bunsho is enabled Write quick expense. | POST |
Optional Scope:
| Name | Description | Endpoint |
|---|---|---|
CONFIG |
Get Expense Configuration information, necessary for expenseTypeId. |
POST |
Dependencies
SAP Concur clients must purchase Concur Expense in order to use this API. This API requires the User v3.1 API which is currently only available to approved early access partners. Please contact your SAP Concur representative for more information.
The partner may use the following SAP Concur APIs to get optional information:
* Expense Group Configurations v3.0, to retrieve the expenseTypeId
* Locations v3.0, to retrieve the location id
Japan Market: If the partner is using this API to provide the e-Bunsho digital timestamp for the receipt, the partner should confirm that the client has e-Bunsho activated in SAP Concur.
Access Token Usage
This API supports both company level and user level access tokens.
Create a Quick Expense
Creates a quick expense without an image.
Scopes
quickexpense.writeonly - Refer to Scope Usage for full details.
Request
URI
Template
https://{datacenterURI}/quickexpense/v4/users/{userID}/context/{contextType}/quickexpenses
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
userID |
string |
- | Required The unique identifier of the SAP Concur user. Use User Profile v1.0 to retrieve the userID. |
contextType |
string |
- | Required The access level of the SAP Concur user, which determines the form fields they can view/modify. Supported value: TRAVELER. |
Headers
- RFC 7231 Accept-Language
- RFC 7231 Content-Type
- RFC 7235 Authorization - Bearer Token that identifies the caller. This is the Company or User access token.
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
Payload
Response
Status Codes
Headers
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
Payload
Example
Request
curl -X POST \
https://us.api.concursolutions.com/quickexpense/v4/users/184dd31a-f48a-4103-879f-c8d45456c7cd/context/TRAVELER/quickexpenses \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access_token}' \
-H 'Content-Type: application/json' \
-H 'concur-correlationid: quick-expense-test' \
-d '{
"comment": "Offsite team lunch.",
"expenseTypeId": "BUSML",
"entryDetails": "test-entry",
"location": {
"city": "Bellevue",
"countryCode": "US",
"countrySubDivisionCode": "US-WA",
"id": "",
"name": ""
},
"paymentTypeId": "CASHX",
"transactionAmount": {
"currencyCode": "USD",
"value": 88.05
},
"transactionDate": "2019-02-04"
}'
Response
201 Created
{
"quickExpenseIdUri": "https://seapr1qes.concurasp.com/quickexpense/v4/users/184dd31a-f48a-4103-879f-c8d45456c7cd/context/TRAVELER/quickexpenses/E018795D2B09094FBF223E209E921B88"
}
Create a Quick Expense with an Image
Creates a quick expense with an image.
Scopes
quickexpense.writeonly - Refer to Scope Usage for full details.
receipts.writeonly - Refer to Scope Usage for full details.
Request
URI
Template
https://{datacenterURI}/quickexpense/v4/users/{userID}/context/{contextType}/quickexpenses/image
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
userID |
string |
- | Required The unique identifier of the SAP Concur user. Use User Profile v1.0 to retrieve the userID. |
contextType |
string |
- | Required The access level of the SAP Concur user, which determines the form fields they can view/modify. Supported values: TRAVELER. |
fileContent |
file |
- | Required The quick expense image. Maximum size 5 MBs. Supported image types are: PNG, PDF, TIFF, JPEG |
Headers
- RFC 7231 Accept-Language
- RFC 7231 Content-Type
- RFC 7235 Authorization - Bearer Token that identifies the caller. This is the Company or User access token.
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
Payload
Response
Status Codes
Headers
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
Payload
Example
Request
curl -X POST \
https://us.api.concursolutions.com/quickexpense/v4/users/184dd31a-f48a-4103-879f-c8d45456c7cd/context/TRAVELER/quickexpenses/image \
-H 'Authorization: Bearer {access_token}' \
-H 'Content-Type: multipart/form-data' \
-H 'concur-correlationid: quick-expense-with-image' \
-H 'content-type: multipart/form-data' \
-F fileContent=@/Users/i845500/Pictures/Snip20180410_1.png \
-F 'quickExpenseRequest={
"comment": "Offsite team lunch.",
"expenseTypeId": "BUSML",
"entryDetails": "test-entry",
"location": {
"city": "Bellevue",
"countryCode": "US",
"countrySubDivisionCode": "US-WA",
"id": "",
"name": ""
},
"paymentTypeId": "CASHX",
"transactionAmount": {
"currencyCode": "USD",
"value": 88.05
},
"transactionDate": "2019-02-04"
}'
Response
201 Created
{
"quickExpenseIdUri": "https://seapr1qes.concurasp.com/quickexpense/v4/users/184dd31a-f48a-4103-879f-c8d45456c7cd/context/TRAVELER/quickexpenses/A0D1CE97B4692B4F8E29BEA53B250E36"
}
Schema
Quick Expense Request
| Name | Type | Format | Description |
|---|---|---|---|
comment |
string |
- | This is a comment attached to the quick expense. |
entryDetails |
string |
- | The quick expense entry details. |
expenseTypeId |
string |
- | Required This is the expense type id of quick expense. Use Expense Group Configurations v3.0 to retrieve the supported expense types. Supported values for a null value are: UNDEF, NULL. NULL can only be used on a POST operation and will be converted to UNDEF. |
location |
- | Location | The location where the quick expense occurred. |
paymentTypeId |
string |
- | This is the payment type id of quick expense. Supported values: CASHX, CPAID, PENDC. |
transactionAmount |
- | Amount | Required The amount of the quick expense. |
transactionDate |
string |
YYYY-MM-DD | Required This is the transaction date of the quick expense. |
vendor |
string |
- | The name of the vendor. |
Location
| Name | Type | Format | Description |
|---|---|---|---|
city |
string |
- | The location city. |
countryCode |
string |
- | The location country ISO 3166-1 code. |
countrySubDivisionCode |
string |
- | The location country sub division ISO 3166-2 code. |
id |
string |
- | The unique identifier of the location. Use Locations v3.0 to retrieve the location id. |
name |
string |
- | The location name. |
Amount
| Name | Type | Format | Description |
|---|---|---|---|
currencyCode |
string |
- | Required The 3-letter ISO 4217 currency code. |
value |
number |
- | Required The amount value. |
Quick Expense Response
| Name | Type | Format | Description |
|---|---|---|---|
quickExpenseIdUri |
string |
- | The quick expense created resource url. |
Error
| Name | Type | Format | Description |
|---|---|---|---|
errorId |
string |
- | The unique identifier of the error. |
errorMessage |
string |
- | Required Message associated with the error. |
httpStatus |
string |
- | The HTTP status associated with the error. |
path |
string |
- | The path to the resource. |
timestamp |
string |
- | The timestamp for the error. |
validationErrors |
array |
validationErrors | An array of validation errors. |
Validation Errors
| Name | Type | Format | Description |
|---|---|---|---|
message |
string |
- | The validation error message. |
source |
string |
- | The source of the validation error. |
Travel Allowance
The Travel Allowance API fetches all the fixed allowance days in the specified expense report. Clients using this API can determine whether an allowance is a full day or partial day allowance.
Limitations: This API is available only for Finland customers. This API is not available in the China Data Center.
- Process Flow
- Products and Editions
- Scope Usage
- Dependencies
- Access Token Usage
- Get Details of Travel Allowance Days
- Schema
- Definitions
Process Flow

Products and Editions
- Concur Expense Professional Edition
- Concur Expense Standard Edition
Scope Usage
| Name | Description | Endpoint |
|---|---|---|
| travelallowance.allowancedays.read | View the allowance days in an expense report | GET |
| EXPRPT | Retrieve the report ID from the Expense Report API to supply to the Travel Allowance API | GET |
Dependencies
The developer must call the Expense Report v3 API prior to using this API, to get the expense report Id.
Access Token Usage
This API will work with Company access token only. A valid Company access token is needed to use this API.
Retrieve a Company Access Token
A Company-level access token is required to create an integration with this API. This allows your integration to get fixed allowance day details of an expense report.
For clients connecting to this API to build a custom integration you will receive client credentials and information on how to generate your company access token or company refresh token from the SAP Concur Web Services resource assigned to assist you with Authentication.
Before making requests to this API, you must obtain an access token from the Authentication API.
The response will include an access_token field, which contains your access token. For subsequent calls, you will need to include this access token in the Authorization header of your calls.
Get Details of Travel Allowance Days
Scopes
travelallowance.allowancedays.read - Refer to Scope Usage for full details.
Request
URI
Template
https://{datacenterURI}/api/v4/travelallowance/allowancedays/companyUUID/{companyUUID}/contexts/{Context}/{ContextId}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
companyUUID |
uuid |
- | Required The company's unique identifier. |
Context |
string |
- | Required For expense reports, the value is EXPENSE_REPORT |
ContextId |
string |
- | Required For expense reports, this is the reportId of the report. |
Headers
- RFC 7231 Content-Type
- RFC 7235 Authorization
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
Payload
- None
Response
Status Codes
- 200 OK
- 204 No Content
- 400 Bad Request
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found
- 405 Method Not Allowed
- 408 Request Timeout
- 500 Internal Server Error
- 502 Bad Gateway
- 503 Service Unavailable
- 504 Gateway Timeout
Headers
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7231 Content-Type
- RFC 7231 Content-Encoding
- RFC 7231 Content-Language
- RFC 7230 Content-Length
Payload
Example
Request
GET https://us.api.concursolutions.com/api/v4/travelallowance/allowancedays/companyUUID/d5528866-51b1-40a1-bab2-76296a106dcd/contexts/EXPENSE_REPORT/B769E8B106C04F30AE27
Authorization: Bearer {token}
Content-Type: application/json
Response
HTTP/1.1 200 OK
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Content-Length: 1270
{
"links": [
{
"rel": "self",
"href": "https://us.api.concursolutions.com/api/v4/travelallowance/allowancedays/companyUUID/d5528866-51b1-40a1-bab2-76296a106dcd/contexts/EXPENSE_REPORT/B769E8B106C04F30AE27"
}
],
"content": [
{
"currencyCode": "EUR",
"fullAllowanceDay": "False",
"allowanceDate": "2018-09-244T12:00:00",
"expenseTransactionDate": "2018-09-244T12:00:00",
"expenseTransactionAmount": 29,
"expenseTypeCode": "MEALS"
},
{
"currencyCode": "EUR",
"fullAllowanceDay": "False",
"allowanceDate": "2018-09-245T12:00:00",
"expenseTransactionDate": "2018-09-245T12:00:00",
"expenseTransactionAmount": 29,
"expenseTypeCode": "MEALS"
},
{
"currencyCode": "EUR",
"fullAllowanceDay": "False",
"allowanceDate": "2018-09-246T12:00:00",
"expenseTransactionDate": "2018-09-246T12:00:00",
"expenseTransactionAmount": 29,
"expenseTypeCode": "MEALS"
}
]
}
Schema
Get Travel Allowance Days Response Schema
| Name | Type | Format | Description |
|---|---|---|---|
expenseTypeCode |
string |
- | Expense Code. For example, MEALS for Travel Allowance. |
fullAllowanceDay |
string |
- | True/False. 'True' means full allowance day and 'False' means partial allowance day. |
currencyCode |
string |
- | The 3-letter ISO 4217 currency code for the expense report currency. The expense report currency is defined as the report creator's default reimbursement currency. |
allowanceDate |
dateTime |
dateTime | Travel Allowance Date. |
expenseTransactionDate |
dateTime |
dateTime | Expense transaction date. |
expenseTransactionAmount |
numeric |
- | Expense transaction amount, in the expense entry currency. |
href |
string |
- | The href represents the target resource identifiers. |
rel |
string |
- | The link relation type describes how the current context (source) is related to the target resource. |
Error
| Name | Type | Format | Description |
|---|---|---|---|
exception |
string |
- | Relative exception details. |
timestamp |
date |
- | Time at which exception occur. |
message |
string |
- | Required Message associated with the error. |
path |
string |
- | Relative data path. |
Definitions
Financial Documents Schemas
Expense
Expense - Employee
| Name | Type | Format | Description |
|---|---|---|---|
employeeCustom1Code through employeeCustom21Code |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters. |
employeeCustom1Value through employeeCustom21Value |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. If configured as a list, this field contains the name of the list item. Maximum length 64 characters. |
employeeFirstName |
String |
- | Alphanumeric. First name of employee. Maximum length 32 characters. |
employeeId |
String |
- | Alphanumeric. Employee ID often also serves as the employee’s Vendor ID for AP system integrations or payroll ID for payroll integrations. Maximum length 128 characters. |
employeeLastName |
String |
- | Alphanumeric. Last name of employee. Maximum length 32 characters. |
employeeMI |
String |
- | Alphanumeric. Middle initial of employee. Maximum length 1 character. |
employeeOrgUnit1Code through employeeOrgUnit6Code |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters. |
employeeOrgUnit1Value through employeeOrgUnit6Value |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. If configured as a list, this field contains the name of the list item. Maximum length 64 characters. |
Expense - Report
| Name | Type | Format | Description |
|---|---|---|---|
cashAdvanceReturnsAmount |
Number |
Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. | Currency. Amount of cash advance returned. |
employeeCurrencyAlphaCode |
String |
3-letter ISO 4217 alpha code. | Alphanumeric. Reimbursement currency. |
homeCountryCode |
String |
ISO 3166-1 alpha-2 country code. | Alphanumeric. The report country. Example: United States is US. |
isTest |
String |
Y/N | Signifies if this report belongs to a test user in system. Y = test user, N = not a test user. |
ledgerCode |
String |
- | Alphanumeric. External accounting system ID. Maximum length 20 characters. |
payrollPayIndicator |
String |
Y/N | This field indicates whether the expense group the report user belongs to is configured to reimburse employees using Payroll. |
payrollPaymentClearingAccountCode |
String |
- | Alphanumeric. SAP customers who reimburse their employees via Payroll need to capture a payroll clearing account code as part of the accounting entry during the financial posting process. Maximum length 128 characters. |
reportCreationDate |
String |
yyyy-mm-ddThr:min:sec.msZ | Date the report was created. Maximum length 24 characters. |
reportCustom1Code through reportCustom20Code |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters. |
reportCustom1Value through reportCustom20Value |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. If configured as a list, this field contains the name of the list item. Maximum length 64 characters. |
reportEndDate |
String |
yyyy-mm-ddThr:min:sec.msZ | End date from the report header. Can be imported from trip data or manually entered. |
reportId |
String |
Unique (across all SAP Concur clients) 32 character alphanumeric. | Alphanumeric. Often used as a voucher number when integrating across AP systems. |
reportKey |
Number |
- | A unique ID (within a single SAP Concur client's company) generated by the system. An alternative to the reportId. Starts with 1 and increments with each expense report. Maximum length 11 characters. |
reportName |
String |
- | Alphanumeric. Report name assigned by employee. Maximum length 40 characters. |
reportOrgUnit1Code through reportOrgUnit20Code |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. The second segment in the fully qualified GL string should use Org Unit 2, except the natural account field. The natural account data is stored in column 167 of the SAE. Maximum length 48 characters. |
reportOrgUnit1Value through reportOrgUnit20Value |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. If configured as a list, this field contains the name of the list item. Maximum length 64 characters. |
reportPaymentProcessingDate |
String |
yyyy-mm-ddThr:min:sec.msZ | The date that the report completed all approvals and was ready to be extracted for payment. Maximum length 24 characters. |
reportStartDate |
String |
- | Report start date. Maximum length 24 characters. |
reportSubmitDate |
String |
- | Date/time the employee submitted the report for approval. Maximum length 24 characters. |
reportUserDefinedDate |
String |
- | Custom date/time specified by user. Maximum length 24 characters. |
revisionNumber |
Number |
- | Report revision number. This will be used to track changes made to posted expenses. Default value is 1. Maximum length 32 characters. |
totalApprovedAmount |
Number |
Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. | Total approved amount of the report. |
versionId |
Number |
- | The version of the FI Document, which is the same as the version of the API endpoint. Maximum length 32 characters. |
Expense - expenseEntry
| Name | Type | Format | Description |
|---|---|---|---|
cardAccountID |
String |
- | Alphanumeric. ID for the card account. This can be used by the receiving system to condense transactions associated with this card. Maximum length 32 characters. |
cardProgramTypeCode |
String |
- | Alphanumeric. The code used to identify the card’s program type. Maximum length 5 characters. |
cardStatementPeriodEndDate |
String |
yyyy-mm-ddThr:min:sec.msZ | The date of the end of the statement period. Maximum length 24 characters. |
cardStatementPeriodStartDate |
String |
yyyy-mm-ddThr:min:sec.msZ | The date of the start of the statement period. Maximum length 24 characters. |
cardTransactionAmount |
Number |
Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. | Currency. Amount of the charge in the spend currency. |
cardTransactionCurrency |
String |
ISO 4217 3-letter alpha code. | Alphanumeric. Currency code for the spend currency. |
cardTransactionID |
String |
- | Reference number from the credit card vendor. Maximum length 32 characters. |
cardTransactionPostedAmount |
Number |
Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. | Amount of the charge in the billing currency of the card. |
cardTransactionPostedCurrency |
String |
ISO 4217 3-letter alpha code. | Alphanumeric. Currency code for the card billing currency. |
clearingAccountCode |
String |
- | Alphanumeric. Contains the expense type account code. - or - If a CBCP Personal expense, the company card clearing account code. - or - If charge is tied to a Statement Report, and accounting code is set for Company Billed card account, the card's accounting code as specified in the Account Code field when creating or editing a CBS account. Maximum length 20 characters. |
entryApprovedAmount |
Number |
Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. | Currency. Amount approved in the reimbursement currency. |
entryCountryCode |
String |
2-character country code. | Alphanumeric. Report entry country code. |
entryCountrySubCode |
String |
- | Alphanumeric. Report entry country sub code. Maximum length 6 characters. |
entryCurrAlphaCode |
String |
ISO 4217 3-letter alpha code. | Alphanumeric. Currency ISO alpha code for the spend currency if not an imported credit card or the invoice currency if this is a credit card. Maximum length 4 characters. |
entryCustom1Code through entryCustom40Code |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters. |
entryCustom1Value through entryCustom40Value |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. If configured as a list, this field contains the name of the list item. Maximum length 64 characters. |
entryDate |
String |
yyyy-mm-ddThr:min:sec.msZ | Date that this expense was incurred (when the money was spent or credit card receipt date). |
entryDescription |
String |
- | Alphanumeric. Expense description as entered by the employee. Maximum length 64 characters. |
entryElectronicReceiptId |
String |
- | GUUID. Electronic receipt ID. Maximum length 24 characters. |
entryExchangeRate |
Number |
- | Rate used to convert from the report entry (spend) currency to the report (reimbursement) currency. Maximum length 23 characters. |
entryExchangeRateDirection |
String |
M/D | Alphanumeric. The direction of the exchange rate conversion. Either: M = Multiply or D = Divide. |
entryId |
String |
- | Report entry sync GUUID unique key. Maximum length 32 characters. |
entryIsBillable |
String |
Y/N | Yes or no is the expense billable. |
entryIsPersonal |
String |
Y/N | Yes or no is the expense personal. |
entryLocationCityName |
String |
- | Alphanumeric. Report entry location city name. Maximum length 64 characters. |
entryLocationName |
String |
- | Alphanumeric. Report entry location name. Maximum length 64 characters. |
entryOrgUnit1Value through entryOrgUnit6Value |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. If configured as a list, this field contains the name of the list item. Maximum length 64 characters. |
entryOrgUnit1Code through entryOrgUnit6Code |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters. |
entryReceiptId |
String |
- | GUUID. Non-electronic receipt image. Maximum length 32 characters. |
entryReceiptType |
String |
T/R/N | Alphanumeric. One of these: T = Tax receipt, R = Regular receipt, or N = No receipt. |
entrySupplierTaxID |
String |
- | Alphanumeric. Report entry XML receipt supplier tax ID. Maximum length 64 characters. |
entryUuid |
String |
- | Report Entry XML Receipt UUID. Maximum length 32 characters. |
entryVendorCode |
String |
- | Alphanumeric. Vendor name list short code. Maximum length 32 characters. |
entryVendorDescription |
String |
- | Alphanumeric. Vendor description. Maximum length 64 characters. |
expensePayIndicator |
String |
Either: 1 = Expense Pay or blank = not Expense Pay. | Indicates whether Expense Pay reimbursed this journal entry. |
expenseTypeCode |
String |
- | Alphanumeric. Code for the expense type. Maximum length 5 characters. |
expenseTypeName |
String |
- | Alphanumeric. Expense type name. Maximum length 64 characters. |
legacyEntryId |
Number |
- | Legacy report entry key. Maximum length 11 characters. |
liabilityAccountCode |
String |
- | Alphanumeric. The liability account code assigned to the funding account paying this entry. Maximum length 48 characters. |
offsetPayType |
String |
Y/N | Use Offsets. Y = Yes, N= No. |
reportEntryPatKey |
String |
- | Alphanumeric. Report Entry Payment Code. Maximum length 4 characters. |
Expense - Allocation
| Name | Type | Format | Description |
|---|---|---|---|
allocationCustom1Code through allocationCustom20Code |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters. |
allocationCustom1Value through allocationCustom20Value |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. If configured as a list, this field contains the name of the list item. Maximum length 64 characters. |
allocationId |
String |
- | GUUID. System-generated unique key for this allocation record. Maximuml length 32 characters. |
allocationPercentage |
Number |
- | Percent of the report entry assigned to this allocation record. Maximum length 11 characters. |
Expense - Journal
| Name | Type | Format (length) | Description |
|---|---|---|---|
accountingTransactionType |
String |
- | Alphanumeric. This is the Intuit QuickBooks specific transaction value. It will be null or a value (GJ, CC, or BILL) depending on if it’s a journalpayee or journalpayer. This determines if a transaction should be posted as Bill or Credit Card in QuickBooks. Maximum length 24 characters. |
amountGrossCard |
Number |
Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. | Amount due to the company card of either CBCP or IBCP type for this detail row. |
amountNetOfReclaim |
Number |
Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. | Currency. Gross Journal amount subtracting reclaimable tax. Or the Net Journal amount adding non-reclaimable tax. |
amountNetOfTax |
Number |
Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. | Currency. Allocated net of reclaim tax. You get this by starting from the net and adding the tax that is not reclaimable, or starting with the gross and subtracting reclaimable. |
amountTax |
Number |
Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. | Currency. This is the Gross Journal amount subtracting the total Tax amount. |
cardTransactionReferenceNumber |
Number |
- | Reference number from the credit card vendor. Maximum length 64 characters. |
journalAccountCode |
String |
- | Alphanumeric. Contains the expense type account code. - or - If a CBCP Personal expense, the company card clearing account code. - or - If charge is tied to a Statement Report, and accounting code is set for Company Billed card account, the card's accounting code as specified in the Account Code field when creating or editing a CBS account. Maximum length 48 characters. |
journalPayee |
String |
- | Alphanumeric. Payment code name for the payee. Maximum length 4 characters. |
journalPayer |
String |
- | Alphanumeric. Payment code name for the payer. Maximum length 4 characters. |
taxGuid |
String |
- | GUUID. Unique identifier associated with the report entry tax allocation. Maximum length 32 characters. |
Expense - cashAdvanceApplication
| Name | Type | Format | Description |
|---|---|---|---|
cashAdvanceApplicationAmount |
Number |
Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. | Currency. Cash advance utilized amount. |
cashAdvanceClearingAccountCode |
String |
- | Alphanumeric. The Account Code is the clearing account code which was configured for the employee in the profile. Maximum length 48 characters. |
cashAdvanceId |
String |
- | GUUID. Unique system ID assigned to the cash advance. Maximum length 32 characters. |
cashAdvanceTransactionType |
Number |
- | Type of transaction: 1 = Issue or return to administrator, 2 = Application, including cash advance return expense within a report, or 3 = System cash advance, from balance carry forward. |
Invoice
Invoice - requestHeader
| Name | Type | Format | Description |
|---|---|---|---|
amountNetInvoice |
Number |
- | The invoice total amount minus the shipping and tax amounts. Maximum length 23 characters. |
amountShippingTotal |
Number |
- | The value for the shipping amount header field. Maximum length 23 characters. |
amountTax |
Number |
- | The total amount of tax on a given invoice. Maximum length 23 characters. |
amountVAT1 through amountVAT4 |
Number |
23 | The individual total VAT amounts for the invoice. Maximum length 23 characters. |
clearingAccountCode |
String |
- | Contains the expense type account code. - or - If a CBCP Personal expense, the company card clearing account code. - or - If charge is tied to a Statement Report, and accounting code is set for Company Billed card account, the card's accounting code as specified in the Account Code field when creating or editing a CBS account. Maximum length 20 characters. |
currencyAlphaCode |
String |
ISO 4217 3-letter alpha code. | Currency ISO alpha code for the spend currency if not an imported credit card or the invoice currency if this is a credit card. |
deliverySlipNumber |
String |
- | Delivery slip number of the receipt which is associated to the invoice line item. Maximum length 256 characters. |
discountPercentage |
Number |
Percentage | Percent value that defines the amount of discount that would be applied. |
discountTermsDays |
Number |
- | Numeric value defining the discount term day amount. Maximum length 3 characters. |
invoiceDate |
String |
YYYY-MM-DD | Date of the invoice. |
invoicePayIndicator |
String |
Y/N- | Signifies if this report belongs to a test user in system. |
invoiceReceivedDate |
String |
YYYY-MM-DD | The date on which the invoice was received. |
isTest |
String |
Y/N | Signifies if this report belongs to a test user in system. |
ledgerCode |
String |
- | External accounting system ID. Maximum length 20 characters. |
ledgerName |
String |
- | The general ledger tied to the invoice. Maximum length 100 characters. |
multiplePurchaseOrder |
String |
Y/N | Defines whether or not multiple purchase orders are tied to the invoice. |
netPaymentTermDays |
Number |
- | Numeric value defining the payment term day amount. Maximum length 3 characters. |
paymentDueDate |
String |
YYYY-MM-DD | The date the payment is due for a given invoice. |
payMethodType |
String |
Drop Down Selector. Valid format options include: ACH, client paid, check, PAYPVD, wire, card, or VCHER. | The method used to pay the invoice, as of the point in time the extract is run. NOTE: It is possible for the method to be changed or updated post-extract through either the Payment Confirmation import (if the client controls payments), or through Invoice Pay (using Payment Manager). |
postingDate |
String |
YYYY-MM-DD | The date the invoice will be posted to the ERP system. |
processCompleteDate |
String |
YYYY-MM-DD | The date the invoice was processed. |
reqKey |
Number |
Integer | An integer that uniquely defines this invoice in SAP Concur. This is the value that the Invoice Confirmation Import uses to match to this particular invoice. |
requestCreationDate |
String |
YYYY-MM-DD | The date the invoice was originally saved. |
requestCustom1Code through requestCustom24Code |
CustomField |
The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters. | |
requestCustom1Value through requestCustom24Value |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters. |
requestDescription |
String |
- | The invoice’s description. Maximum length 250 characters. |
requestId |
String |
- | The unique identification assigned to the invoice. Maximum length 20 characters. |
requestOrgUnit1Code through requestOrgUnit6Code |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters. |
requestOrgUnit1Value through requestOrgUnit6Value |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters. |
requestTitle |
String |
- | The invoice name. Maximum length 100 characters. |
requestTotal |
Number |
Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. | The sum of all Line Item Amounts plus Shipping Amount and Tax Amount for the invoice. |
revisionNumber |
Number |
- | Invoice revision number. Default value is 1. Maximum length 32 characters. |
submitDate |
String |
YYYY-MM-DD | Date/time the employee submitted the invoice for approval. |
vendorInvoiceNumber |
String |
- | The invoice number assigned by the vendor. Maximum length 50 characters. |
versionId |
String |
- | The version of the FI Document, which is the same as the version of the API endpoint. Maximum length 32 characters. |
Invoice - ownerEmployee
| Name | Type | Format | Description |
|---|---|---|---|
employeeCustom1Code through employeeCustom21Code |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters. |
employeeCustom1Value through employleeCustom21Value |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters. |
employeeFirstName |
String |
- | First name of employee. Maximum length 32 characters. |
employeeId |
String |
- | Employee ID often also serves as the employee’s Vendor ID for AP system integrations or Payroll ID for Payroll integrations. Maximum length 48 characters. |
employeeLastName |
String |
- | Last name of employee. Maximum length 32 characters. |
employeeMI |
String |
- | Middle initial of employee. Maximum length 1 character. |
employeeOrgUnit1Value through employeeOrgUnit6Value |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters. |
Invoice - Vendor
| Name | Type | Format | Description |
|---|---|---|---|
vendorCode |
String |
- | The financial system's code for this vendor. Maximum length 23 characters. |
vendorContactFirstName |
String |
- | Buyer contact for the vendor record’s first name. Maximum length 255 characters. |
vendorContactLastName |
String |
- | Buyer contact for the vendor record’s last name. Maximum length 255 characters. |
vendorName |
String |
- | The financial system's name for this vendor. Maximum length 255 characters. |
vendorRemitToAddressCode |
String |
Less than or equal to 64. | The financial system's code for this address. |
Invoice - lineItem
| Name | Type | Format | Description |
|---|---|---|---|
allocationAccountCode |
String |
- | The Account Code for the Allocation related to this Journal Entry. Maximum length 20 characters. |
allocationCustom1Code through allocationCustom20Code |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters. |
allocationCustom1Value through allocationCustom20Value |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters. |
allocationKey |
Number |
- | System-generated unique key for this allocation record. Maximum length 13 characters. |
allocationPercentage |
Number |
- | Percent of the report entry assigned to this allocation record. Maximum length 64 characters. |
journal |
String |
- | Container for journal entries tied to the allocation. Maximum length 48 characters. |
accountCode |
Number |
- | The financial system accounting code value tied to the invoice line. Maximum length 20 characters. |
amountGross |
Number |
- | The gross amount (total amount) of the invoice line item. Maximum length 23 characters. |
amountNet |
Number |
- | The net amount of the invoice line item not including shipping and tax. Maximum length 23 characters. |
amountShipping |
Number |
Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. | The value for the Shipping Amount header field. Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. |
expenseTypeCode |
String |
- | Code for the expense type so a value that isn’t language dependent is returned. Maximum length is 7 characters. |
expenseTypeName |
String |
- | Expense type name. Maximum length 64 characters. |
externalLineItemId |
String |
- | The PO Line item associated with to the Invoice. Maximum length 100 characters. |
lineItemCode |
String |
- | The Primary Key value for the expense type. Maximum length 7 characters. |
lineItemCustom1Code through lineItemCustom20Code |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters. |
lineItemCustom1Value through lineItemCustom20Value |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters. |
lineItemDeliverySlipNumber |
String |
- | Delivery Slip Number of the receipt which is associated to the invoice line item. Maximum length 256 characters. |
lineItemDescription |
String |
- | The description of the goods or services being purchased on the individual invoice line. Maximum length 255 characters. |
lineItemPurchaseOrderNumber |
String |
- | The purchase order number associated with the invoice line item (for a multiple purchase order-based invoice), or the purchase order number associated with the header (for a single purchase order-based invoice). Maximum length 10 characters. |
lineItemQuantity |
String |
- | The quantity of the line item. Maximum length 23 characters. |
lineItemSequenceOrder |
Number |
Integer | Line item number for the line item related to this Journal Entry. Value is dynamically generated by the system based on the number of lines. |
lineItemUnitPrice |
Number |
- | The quantity unit price for the item being purchased. Maximum length 23 characters. |
poLineNumber |
Number |
- | The PO line item number associated to the payment request. Maximum length 48 characters. |
receiptNumber |
Number |
- | The Goods Receipt number. Maximum length 256 characters. |
receiptQuantity |
Number |
- | The Goods Received quantity. Maximum length 23 characters. |
receiptItemID |
Number |
- | The ID of the Goods Receipt tied to the Invoice and PO Line. Maximum length 48 characters. |
Invoice - Tax
| Name | Type | Format | Description |
|---|---|---|---|
amountTax |
Number |
- | The taxation amount that exists on the invoice line. Maximum length 23 characters. |
taxCode |
String |
- | Tax code assigned to this tax authority for the expense type entered on the expense entry. Maximum length 20 characters. |
taxField |
String |
- | Defines which database field the tax resides in. Maximum length 20 characters. |
Cash Advance
Cash Advance - employeeData
| Name | Type | Format | Description |
|---|---|---|---|
employeeCustom1Code through employeeCustom21Code |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters. |
employeeCustom1Value through employeeCustom21Value |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 64 characters. |
employeeFirstName |
String |
- | Alphanumeric. First name of employee. Maximum length 32 characters. |
employeeId |
String |
- | Alphanumeric. Employee ID often also serves as the employee’s Vendor ID for AP system integrations or Payroll ID for Payroll integrations. Maximum length 128 characters. |
employeeLastName |
String |
- | Alphanumeric. Last name of employee. Maximum length 32 characters. |
employeeMI |
String |
- | Alphanumeric. Middle initial of employee. Maximum length 1 character. |
employeeOrgUnit1Code through employeeOrgUnit6Code |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters. |
employeeOrgUnit1Value through employeeOrgUnit6Value |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 64 characters. |
Cash Advance - cashAdvanceData
| Name | Type | Format | Description |
|---|---|---|---|
cardAccountID |
String |
- | Alphanumeric. ID will be used initially by the receiving system to “condense” transactions associated with this card. It will also be used to retrieve the card number in a separate API call. Maximum length 32 bytes. |
cardTransactionAmount |
Number |
Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. | Currency. Amount of the charge in the spend currency. |
cardTransactionCurrency |
String |
ISO 4217 3-letter alpha code. | Alphanumeric. Currency code for the spend currency. |
cardTransactionID |
String |
- | Alphanumeric. Calculated value assigned to this card entry during the import process. Maximum length 32 characters. |
cardTransactionPostedAmount |
Number |
Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. | Currency. Amount of the charge in the billing currency of the card. |
cardTransactionPostedCurrency |
String |
ISO 4217 3-letter alpha code. | Alphanumeric. Currency code for the card billing currency. |
cashAdvanceId |
String |
- | GUUID. Unique system ID assigned to the cash advance. Maximum length 32 characters. |
clearingAccountCode |
String |
- | Alphanumeric. Contains the expense type account code. - or - If a CBCP Personal expense, the company card clearing account code. - or - If charge is tied to a Statement Report, and accounting code is set for Company Billed card account, the card's accounting code as specified in the Account Code field when creating or editing a CBS account. Maximum length 20 characters. |
countryCode |
String |
ISO 3166-1 alpha-2 country code. | Alphanumeric. The report country. Example: United States is US. |
countrySubCode |
String |
- | Alphanumeric. Report entry country sub code. Maximum length 6 characters. |
currencyAlphaCode |
String |
ISO 4217 3-letter alpha code. | Alphanumeric. Currency ISO alpha code for the spend currency if not an imported credit card or the invoice currency if this is a credit card. |
currencyNumCode |
String |
ISO 4217 3-letter alpha code. | Alphanumeric. Currency code for the transaction currency using ISO number code. |
employeeCurrencyAlphaCode |
String |
ISO 4217 3-letter alpha code. | Alphanumeric. Reimbursement currency. |
exchangeRate |
Number |
- | Rate used to convert from the report entry (spend) currency to the report (reimbursement) currency. Maximum length 23 characters. |
expensePayIndicator |
String |
Y/N | Indicates whether Expense Pay reimbursed this journal entry. Either: Y = Expense Pay or N = not Expense Pay. |
issuedDate |
String |
yyyy-mm-ddThr:min:sec.msZ | Date of issue. |
isTest |
String |
Y/N | Signifies if this report belongs to a test user in system. |
entrylocationName |
String |
- | Alphanumeric. The report entry location name (for example, city name). Maximum length 64 characters. |
name |
String |
- | Alphanumeric. Cash advance request name. Maximum length 40 characters. |
paymentMethod |
String |
0 = Non-Expense Pay method used for disbursement or 1 = Expense Pay method used for disbursement. | Alphanumeric. The method used, either Expense Pay or Other, used for disbursement of the cash advance. |
purpose |
String |
- | Alphanumeric. Describes the purpose of cash advance issued. Maximum length 2,000 characters. |
requestAmount |
Number |
Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. | Currency. For issue journal record, the total amount of the cash advance in the cash advance transaction currency. |
requestDate |
String |
yyyy-mm-ddThr:min:sec.msZ | Date of cash advance request from the detailed cash advance record. |
requestedDisbursementDate |
String |
yyyy-mm-ddThr:min:sec.msZ | Cash advance disbursement date. |
transactionType |
String |
1 = Issue or Return to Administrator, 2 = Application, including Cash Advance Return expense within a report, or 3 = System Cash advance, from balance carry forward. | Alphanumeric. Type of transaction. |
travelEndDate |
String |
yyyy-mm-ddThr:min:sec.msZ | The last day of the trip on the assigned travel request itinerary. |
travelStartDate |
String |
yyyy-mm-ddThr:min:sec.msZ | The first day of the trip on the assigned travel request itinerary. |
Cash Advance - journalData
| Name | Type | Format | Description |
|---|---|---|---|
accountCode |
String |
- | Alphanumeric. Contains the expense type account code. - or - If a CBCP Personal expense, the company card clearing account code. - or - If charge is tied to a Statement Report, and accounting code is set for Company Billed card account, the card's accounting code as specified in the Account Code field when creating or editing a CBS account. Maximum length 48 characters. |
amount |
Number |
Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. | Currency. Value, as credit or debit, of the amount to be exchanged between the payer and payee for this expense account code (not an absolute value) EXAMPLES: Value of zero, credit, or debit, as the following: 0 (Zero) "0," + (Plus / Debit) "+50.00," or - (Minus / Credit) "-50.00." |
debitOrCredit |
String |
DR/CR | Alphanumeric. Either: DR = Debit or CR = credit. |
payee |
String |
- | Alphanumeric. Either a company or an employee depending on the payment type. Maximum length 64 characters. |
payer |
String |
- | Alphanumeric. Either a company or an employee depending on the payment type. Maximum length 64 characters. |
paymentCode |
String |
- | Alphanumeric. The payment code for either a payee or payer. Maximum length 80 characters. |
Financial Integration Service Use Cases
- Expense Posting Without Tax
- Simple Out-of-Pocket Cash Expense
- VAT Handling
- Non-Deductible VAT
- Itemization
- Cost Allocation
- Cash Advances
- Credit Card Types
- Employee Paid Credit Card
- Payment via Employee Vendor Account
- Payment via Credit Card Vendor Account (Split Payment)
- Credit Transaction via Credit Card Vendor Account (Split Payment)
- Simple IBCP Corporate Card Charge With Itemization
- IBCP With Personal Expense: No Out-of-Pocket
- IBCP (With Offsets) With Personal Expense: Out-of-Pocket Greater Than Personal Expense
- IBCP (With Offsets) With Personal Expense: Out-of-Pocket Less Than Personal Expense
- Company Paid Credit Card
- CBCP Corporate Card Charge for Entirely Personal Expense (Net Due Company With Consolidated or Verbose Extract)
- CBCP Corporate Card Charge with Itemization and Personal Expense (Net Due Employee With Consolidation)
- CBCP Corporate Card Charge for Entirely Personal Expense (Net Due Company With Verbose Extract)
- CBCP Corporate Card Charge With Itemization and Personal Expense (Net Due Employee Without Offsets)
Overview
The use case examples below illustrate expense scenarios and the related posting records. Posting records will vary based on app design. The use case documentation is not meant to be a comprehensive list of all use cases and expense scenarios. However, the JSON from the Financial Integration Service will provide all the required data to support the all potential financial use cases.
Simple Expense Posting Without Tax
Simple Out-of-Pocket Cash Expense
Description
Very simple expense report with only a few expense items without VAT, for example, US expense report.
Posting Example
Expense Report with one expense item: Taxi – USD 10
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Expense (Taxi) | USD 10 | - |
| Employee Vendor | - | USD 10 |
Standard Accounting Extract Details
Simple Out-of-Pocket Cash Credit
Description
The user receives a USD 50 cash rebate for a hotel stay that was fully reimbursed on a previous expense report. Being a good corporate citizen the user enters a single USD 50 cash credit transaction and assigns it to the Expense Type "Hotel." The expense is a legitimate business expense, not a personal expense. It is not itemized.
Posting Example
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Expense (Hotel) | - | USD 50 |
| Employee Vendor | USD 50 | - |
Standard Accounting Extract Details
Simple Personal Car Mileage Expense
Description
The user enters a single personal car mileage transaction for a round trip to the airport of 60 miles. The expense is a legitimate business expense, not a personal expense. It is not itemized.
Posting Example
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Expense (Mileage) | USD 24.30 | - |
| Employee Vendor | - | USD 24.30 |
Standard Accounting Extract Details
Travel Allowances – Company Specific Rate Greater Than Government Rate
Description
A German traveler receives meal per diems that are higher the legal rates. In this case he gets EUR 50 instead of the EUR 24 legal amount allowed for a full day. As a result the amount reimbursed to the employee over the legal daily rate is taxable to the employee.
Posting Example
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Expense (Meals) | EUR 50 | - |
| Employee Vendor (non-taxable) | - | EUR 24 |
| Employee Vendor (taxable) | - | EUR 26 |
Standard Accounting Extract Details
VAT Handling
The SAP Concur system, when configured and applicable, will calculate the related VAT tax for a given transaction. This determination relies on the customer’s tax configuration and will vary by customer and country. The posting document will include all related VAT amounts that are calculated.
How the VAT is handled is determined based on the Tax Code customization in ERP and the related VAT use cases that the partner application supports.
Expense Posting With Single Tax Item
Description
Very simple expense report with only a few expense items with VAT, for example, German expense report.
Posting Example
The posting below is one example of how the expense gets recorded by the customer based on their ERP set up and requirements.
Expense Report with one expense item: Laundry – EUR 10 (including 16 % - EUR 1.60 VAT).
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Expense (amount net of tax) | EUR 8.40 | - |
| VAT | EUR 1.60 | - |
| Employee Vendor (gross amount) | - | EUR 10 |
Non-Deductible VAT
The SAP Concur system, when configured and applicable, will calculate the related VAT tax for a given transaction. In some cases, this tax is deductible if it meets certain country-based requirements. In other cases, it is not deductible. This determination relies on the customer’s tax configuration and will vary by customer and country. The posting document will include all related VAT amounts that are calculated.
How the VAT is handled is determined based on the Tax Code customizing in ERP and the related VAT use cases that the partner application supports.
Description
Very simple expense report with only a few expense items with VAT, for example, German expense report.
Posting Example
The posting below is one example of how the expense gets recorded by the customer based on their ERP set up and requirements.
Expense Report with one expense item: Gas – EUR 100 (including 15.97% - EUR 15.97 VAT)
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Expense (amount net of tax) | EUR 84.03 | - |
| Non-deductible VAT Expense | EUR 15.97 | - |
| Employee Vendor (gross amount) | - | EUR 100 |
Expense Posting With Multiple Tax Items
Description
For a country like Canada, with multiple tax jurisdictions the entry may have multiple tax lines representing calculated VAT for each jurisdiction. The posting document will include all related tax lines and corresponding tax amounts.
Posting Example
The posting below is one example of how the expense gets recorded by the customer based on their ERP set up and requirements.
Expense Report with one expense item: Local Phone – CAD 100 with multiple tax jurisdictions (for example, tax type 1, tax type 2).
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Expense (amount net of tax) | 88.50 CAD | - |
| Tax Type 1 | CAD 4.42 | - |
| Tax Type 2 | CAD 7.08 | - |
| Employee Vendor (gross amount) | - | CAD 100 |
Partially Deductible VAT
Description
In some cases it could be possible that the whole VAT amount is not deductible. This case has similar posting options as non-deductible VAT.
Posting Example
The posting below is one example of how the expense gets recorded by the customer based on their ERP set up and requirements.
For a hotel receipt of CAD 55 (including 11.5% - CAD 6.32 VAT) the VAT is only deductible by 50%.
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Expense (amount net of tax) | CAD 48.68 | - |
| VAT | CAD 3.16 | - |
| Non-deductible VAT | CAD 3.16 | - |
| Employee Vendor (gross amount) | - | CAD 55 |
Foreign Expense Report Without VAT
Description
The SAP Concur system, when configured and applicable, will calculate the related VAT tax for a given transaction. In some cases, this tax is deductible if it meets certain country-based requirements. In other cases, it is not deductible. This determination relies on the customer’s tax configuration and will vary by customer and country. The posting document will include all related VAT amounts that are calculated.
In case an employee from a country with VAT enters a foreign receipt and the included VAT is not claimable, the document has to be posted with a 0% VAT tax code. In SAP Concur this tax code is normally customized for the tax authority in the non-domestic code field. Again, this will vary based on the exact use case and customer’s tax configuration.
Posting Example
A UK employee submits an entry for a US-based training. In this case the posting document will include U.S tax included on the receipt and the posting will be handled in the ERP according to the desired posting record. It’s common that the posting record will include the tax amount as part of the overall expense (in this case Hotel) but a valid tax code with a 0% rate will also be included. This allows the customer to report on foreign taxes paid but which are not reclaimable.
The posting below is one example of how the expense gets recorded by the customer based on their ERP set up and requirements.
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Room Rate | GBP 60.24 | - |
| Hotel Tax | GBP 20.08 | - |
| Card Vendor | - | GBP 80.32 |
Itemization
Itemized Expense Items
Description
John flew to New York to meet with a client and stayed one night at the Marriot. An original receipt is split into several parts, for example, lodging costs per night, room tax, and breakfast. All items should be processed separately in the Journal Section, SAE, and JSON.
Posting Example
For a hotel receipt of USD 325 where the costs per night and other expenses should be posted separately.
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Room Rate | USD 250 | - |
| Room Tax | USD 50 | - |
| Breakfast | 25 USD | - |
| Employee Vendor | - | USD 325 |
Standard Accounting Extract Details
Cost Allocation
What is cost allocation? Allocation is defined as a part of cross-charging is the ability to assign cost of an expense to multiple organizational units such as department, cost center, project code, etc.
When allocating the expense across multiple cost centers, the user needs to pick the correct code from the most granular level which may be from the Expense Entry, Journal Entry, and/or Allocation Entry depending on whether or not the customer is configured to use the allocation fields. Cost center codes should NEVER be picked up from the Employee Entry section because an employee may have to charge another department for a percentage of a transaction.
Expense With Multiple Cost Allocations
Description
Similar to the itemized expense example, however, the breakfast cost is allocated between two different cost centers.
Posting Example
For a hotel receipt of USD 325 where the costs per night and other expenses should be posted separately.
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Room Rate | USD 250 | - |
| Room Tax | USD 50 | - |
| Breakfast | 25 USD | - |
| Employee Vendor | - | USD 325 |
Extract Details
Standard Accounting Extract Details
NOTE: The room rate and room tax is charged to the same cost center as in the itemized expense example. Only the breakfast cost is allocated 50% between two different cost centers: 0021-Bellevue1 and Top Management. The allocation section is towards the bottom of the JSON.
Cash Advances
Issuance
Paid Cash
Description
An employee requests a cash advance to be paid in cash or via transfer.
Posting Example
Employee requests a cash advance of USD 7000 for trip to TechEd.
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Cash Advance Clearing Account | USD 7000 | - |
| Employee Vendor | - | USD 7000 |
Standard Accounting Extract Details
Note: This extract example is the same as Itemized Expense Items.
Application
Cash Advance Is Lower Than the Payout Amount
Description
The employee enters an expense report and assigns a cash advance. This cash advance reduces the employee’s payout amount. Only the difference between the sum of the expense items paid by the employee and the cash advance will be paid to the employee.
Posting Example
The user has requested and received an GBP 300 cash advance. In the course of travel the user incurs the following cash expenses: GBP 245 for a rental car, GBP 60 for a business meal, and GBP 10 for parking. After returning from travel the user finds the GBP 300 cash advance has been issued via the corporate card import process. He assigns the GBP 300 cash advance to an expense report and enters the three cash expenses and submits. The expenses are not itemized. The expenses are legitimate business expenses.
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Car Rental | GBP 245 | - |
| Meal | GBP 60 | - |
| Parking | GBP 10 | - |
| Cash Advance Clearing Account | GBP 300 | - |
| Employee Vendor | - | GBP 15 |
Extract Details
Cash Advance Is Higher Than the Payout Amount
Description
The employee enters an expense report and assigns a cash advance. If the cash advance is higher than the sum of the expense items paid by the employee the employee owes the difference to the company.
Posting Example
The user has requested and received a GBP 400 cash advance and during travel spends GBP245 on a rental car, GBP 60 on a business meal, and GBP 10 on parking. The user assigns the GBP 400 cash advance to the expense report and enters the three cash expenses and submits. The expenses are not itemized. The expenses are legitimate business expenses. Because the total of the cash advance exceeds the sum of the business expenses the net result of the expense report is that the employee owes the company the balance. The employee will write a check to the company for the balance (GBP 85) and enter a cash advance return transaction in that amount to net the expense report to zero.
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Car Rental | GBP 245 | - |
| Meals | GBP 60 | - |
| Parking | GBP 10 | - |
| Cash Advance Clearing Account | - | GBP 400 |
| Employee Vendor | GBP 85 | - |
Extract Details
Credit Card Types
- IBIP - Individual Bill – Individual payment paid by employee (employee liability).
- IBCP - Individual Bill – Company payment split payment (employee liability for personal use. Company liability for approved business expenses).
- CBCP - Company Bill – Company payment paid by company (company liability).
Employee Paid Credit Card
Payment via Employee Vendor Account
Description
Credit card items with employee liability should be paid to the employee’s bank account like cash paid expenses. (IBIP)
Posting Example
Expense Report with one employee paid credit card item: Taxi - USD 10.
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Expense (Taxi) | USD 10 | - |
| Employee Vendor | - | USD 10 |
Payment via Credit Card Vendor Account (Split Payment)
Description
Approved business expenses should be paid to the credit card instead of the employee’s bank account. (IBCP)
Posting Example
Car rental was paid with IBIP card for USD 56.10.
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Expense (Car Rental) | USD 56.10 | - |
| Credit Card Vendor | - | USD 56.10 |
Credit Transaction via Credit Card Vendor Account (Split Payment)
Example
The user receives a USD 349 credit on the corporate card for an unused airline ticket. The credit transaction is displayed as a pre-populated corporate card transaction and the user selects it and submits an expense report. The expense is a legitimate business expense, not a personal expense. It is not itemized.
Posting
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Expense (Airfare) | - | USD 349 |
| Credit Card Vendor | USD 349 | - |
Simple IBCP Corporate Card Charge With Itemization
Example
John flew to New York to meet with a client and stayed one night at the Marriot. An original receipt is split into several parts, for example, lodging costs per night, room tax, and breakfast. All items should be processed separately in the Journal Section, SAE, and JSON.
Posting Example
For a hotel receipt of USD 325 where the costs per night and other expenses should be posted separately.
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Room Rate | USD 250 | - |
| Room Tax | USD 50 | - |
| Breakfast | USD 25 | - |
| Employee Vendor | - | USD 325 |
IBCP With Personal Expense: No Out-of-Pocket
NOTE: Personal expenses paid by an IBCP credit card will not be included in the JSON.
Example
John flew to New York to meet with a client and stayed one night at the Marriot. An original receipt is split into several parts, for example, lodging costs per night, room tax, and breakfast. All items should be processed separately in the Journal Section, SAE, and JSON. Since breakfast is a personal expense, it will be included in the extract but NOT in the JSON.
Posting Example
For a hotel receipt of USD 325 where the costs per night and other expenses should be posted separately.
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Room Rate | USD 250 | - |
| Room Tax | USD 50 | - |
| Breakfast (personal) | USD 25 | - |
| Employee Vendor | - | USD 325 |
IBCP with Personal Expense Where Out-of-Pocket Exceeds the Personal Expense
NOTE: Personal expenses paid by an IBCP credit card will not be included in the JSON when a non-offsetting payment is used because it’s not relevant to the company’s accounting record.
Without Offsetting
Example
The user assigns a pre-populated corporate card transaction to the expense report. The transaction is a Hotel expense in the amount of USD 284. The hotel expense consists of a two-night stay at USD 125 per night and the user had a USD 20 dinner after checking in and ordered an in-room movie for USD 14 that the company does not reimburse for. The expense is itemized. The expense is a legitimate business expense with the exception of the in-room movie that the user marks as a non-reimbursable expense on the expense report. The expense report also includes an out-of-pocket cash transaction for a taxi at USD 35.
Posting
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Room Rate | USD 125 | - |
| Room Rate | USD 125 | - |
| Dinner | USD 20 | - |
| Taxi | USD 35 | - |
| Credit Card Vendor | - | USD 270 |
| Employee Vendor | - | USD 35 |
With Offsetting
When using offsets the amount due the employee for out-of-pocket expenses is netted (or offset) against the amount marked as personal, resulting in an entry reflecting either the final amount the employee owes the company (assumes personal exceeds out of pocket) or final amount company owes the employee (reduced by any personal amounts).
Posting
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Room Rate | USD 125 | - |
| Room Rate | USD 125 | - |
| Dinner | USD 20 | - |
| Taxi | USD 14 | - |
| Taxi | USD 21 | - |
| Credit Card Vendor | - | USD 284 |
| Employee Vendor | - | USD 21 |
Extract Details
IBCP With Personal Expense Where Out-of-Pocket Is Less Than Personal Expense
NOTE: Personal expenses paid by an IBCP credit card will not be included in the JSON when a non-offsetting payment is used because it’s not relevant to the company’s accounting record.
Without Offsetting
Example
The user assigns a pre-populated corporate card transaction to the expense report. The transaction is a Hotel expense in the amount of USD 284. The hotel expense consists of a two-night stay at USD 125 per night and the user had a USD 20 dinner after checking in and ordered an in-room movie for USD 14 that the company does not reimburse for. The expense is itemized. The expense is a legitimate business expense with the exception of the in-room movie that the user marks as a non-reimbursable expense on the expense report. The expense report also includes an out-of-pocket cash transaction for parking in the amount of USD 5.
Posting
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Hotel | USD 125 | - |
| Hotel | USD 125 | - |
| Dinner | USD 20 | - |
| Parking | USD 5 | - |
| Credit Card Vendor | - | USD 275 |
With Offsetting
When using offsets the amount due the employee for out-of-pocket expenses is netted (or offset) against the amount marked as personal, resulting in an entry reflecting either the final amount the employee owes the company (assumes personal exceeds out of pocket) or final amount company owes the employee (reduced by any personal amounts).
Posting
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Hotel | USD 125 | - |
| Hotel | USD 125 | - |
| Dinner | USD 20 | - |
| Parking | USD 5 | - |
| Credit Card Vendor | - | USD 275 |
Company Paid Credit Card
CBCP Corporate Card Charge for Entirely Personal Expense (Net Due Company With Consolidated or Verbose Extract)
Example
The employee mistakenly uses the corporate card to pay for tolls (USD 32) and dues (USD 49) expense totaling USD 81. When the corporate card transaction feed populates the company card page the employee must deal with this transaction. The employee assigns the USD 81 corporate card transaction to an expense report, marks it as a non-reimbursable expense and submits the report for approval.
Posting
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Employee Vendor | USD 49 | - |
| Credit Card Clearing | - | USD 49 |
| Credit Card Clearing | USD 49 | - |
| Credit Card Vendor | - | USD 49 |
| Employee Vendor | USD 32 | - |
| Credit Card Clearing | - | USD 32 |
| Credit Card Clearing | USD 32 | - |
| Credit Card Vendor | - | USD 32 |
CBCP Corporate Card Charge with Itemization and Personal Expense (Net Due Employee With Consolidation)
Example
The user assigns a pre-populated corporate card transaction to the expense report. The transaction is a Hotel expense in the amount of USD 284. The hotel expense consists of a two-night stay at USD 125 per night and the user had a USD 20 dinner after checking in and ordered an in-room movie for USD 14 that the company does not reimburse for. The expense is itemized. The expense is a legitimate business expense with the exception of the in-room movie that the user marks as a non-reimbursable expense on the expense report. The expense report also includes an out-of-pocket cash transaction for a taxi at USD 35.
Posting
Posting Record
Expense Report:
| Account | Debit | Credit |
|---|---|---|
| Room Rate | USD 125 | - |
| Room Rate | USD 125 | - |
| Dinner | USD 20 | - |
| Taxi | USD 32 | - |
| Employee Vendor (personal expense) | USD 14 | - |
| Employee Vendor | - | USD 35 |
| Credit Card Clearing | - | USD 284 |
CBCP Corporate Card Charge for Entirely Personal Expense (Net Due Company With Verbose Extract)
Example
The employee mistakenly uses the corporate card to pay for a personal dinner expense of USD 300. When the corporate card transaction feed populates the company card page the employee must deal with this transaction. The employee assigns the USD 300 corporate card transaction to an expense report, marks it as a non-reimbursable expense and submits the report for approval.
Posting
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Employee Vendor | USD 300 | - |
| Credit Card Clearing Account | - | USD 300 |
| Credit Card Clearing Account | USD 300 | - |
| Credit Card Vendor | - | USD 300 |
CBCP Corporate Card Charge with Itemization and Personal Expense (Net Due Employee With No Offsets)
Example
The user assigns a pre-populated corporate card transaction to the expense report. The transaction is a Hotel expense in the amount of USD 284. The hotel expense consists of a two-night stay at USD 125 per night and the user had a USD 20 dinner after checking in and ordered an in-room movie for USD 14 that the company does not reimburse for. The expense is itemized. The expense is a legitimate business expense with the exception of the in-room movie that the user marks as a non-reimbursable expense on the expense report. The expense report also includes an out-of-pocket cash transaction for a taxi at USD 35.
Posting
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Room Rate | USD 125 | - |
| Room Rate | USD 125 | - |
| Dinner | USD 20 | - |
| Taxi | USD 35 | - |
| Employee Vendor (out of pocket) | - | USD 35 |
| Employee Vendor (personal expense) | USD 14 | - |
| Credit Card Vendor | - | USD 284 |
Financial Integration Use Cases Extract Information
- Simple Expense Posting Without Tax
- VAT Handling
- Itemization
- Cash Advances
- Credit Card Items
- Payment via Employee Vendor Account
- Payment via Credit Card Vendor Account (Split Payment)
- Credit Transaction via Credit Card Vendor Account (Split Payment)
- Simple IBCP Corporate Card Charge With Itemization
- IBCP With Personal Expense: No Out-of-Pocket
- IBCP with Personal Expense Where Out-of-Pocket Exceeds the Personal Expense
- IBCP With Personal Expense Where Out-of-Pocket Less Than Personal Expense
- CBCP Corporate Card Charge for Entirely Personal Expense (Net Due Company With Consolidated or Verbose Extract)
- CBCP Corporate Card Charge with Itemization and Personal Expense (Net Due Employee With Consolidation)
- CBCP Corporate Card Charge for Entirely Personal Expense (Net Due Company With Verbose Extract)
- CBCP Corporate Card Charge with Itemization and Personal Expense (Net Due Employee With No Offsets)
Note: The extract file excerpts in this document are a reference point for those developers who have used those files for prior financial integrations. This excerpt is intended to help those developers transition from an extract file to the Financial Integration Service. This allows you to identify what you have been using from the extract file and to locate the same data in the new JSON response. If you have not used the extract file previously, the extract file excerpts can be skipped.
Simple Expense Posting Without Tax
Simple Out-of-Pocket Cash Expense
The Payer in this instance is the company; the Payee is the employee. Since it is not an itemized expense the Entry Transaction Type is REG. Because it is a legitimate business expense the ‘Is Personal’ flag is set to ‘N’. The employee will be reimbursed for this transaction.
| [61] entry_id | [64] Entry Transaction Date | [70] Vendor Name | [63] Expense Type | [68] Is Personal | [62] Entry Transaction Type | [163] Payer Payment Type | [165] Payee Payment Type | [169] Journal Amount | [168] Debit Credit | [167] Account Code | [177] Cash Advance Amount | [185] Cash Advance Transaction Type |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 8337 | 03/05/2016 | - | Taxi | N | REG | COMPANY | EMPLOYEE | USD 10 | DR | 474230 | - | - |
Simple Out-of-Pocket Cash Credit
The Payer in this instance is the employee; the Payee is the company. Since it is not an itemized expense the Entry Transaction Type is REG. Because it is a legitimate business expense the ‘Is Personal’ flag is set to ‘N’. The company will be reimbursed for this transaction.
| [61] entry_id | [64] Entry Transaction Date | [70] Vendor Name | [63] Expense Type | [68] Is Personal | [62] Entry Transaction Type | [163] Payer Payment Type | [165] Payee Payment Type | [169] Journal Amount | [168] Debit Credit | [167] Account Code | [177] Cash Advance Amount | [185] Cash Advance Transaction Type |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 4178 | 5/28/2019 | Ritz Carlton | Booking Fees (Hotel) | N | REG | EMPLOYEE | COMPANY | USD -50 | CR | 5 | - | - |
Simple Personal Car Mileage Expense
The Payer in this instance is the company; the Payee is the employee. Since it is not an itemized expense the Entry Transaction Type is REG. Because it is a legitimate business expense the ‘Is Personal’ flag is set to ‘N’. The employee will be reimbursed for this transaction.
| [61] entry_id | [64] Entry Transaction Date | [70] Vendor Name | [63] Expense Type | [68] Is Personal | [62] Entry Transaction Type | [163] Payer Payment Type | [165] Payee Payment Type | [169] Journal Amount | [168] Debit Credit | [167] Account Code | [177] Cash Advance Amount | [185] Cash Advance Transaction Type |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 4173 | 5/23/2019 | - | Mileage | N | REG | COMPANY | EMPLOYEE | USD 24.30 | DR | 54 | - | - |
Travel Allowances: Company Specific Rate Greater Than Government Rate
The Payer in this instance is the company; the Payee is the employee. Since it is not an itemized expense the Entry Transaction Type is REG. Because it is a legitimate business expense the ‘Is Personal’ flag is set to ‘N’. The employee will be reimbursed for this transaction.
The report entry item will be split into 2 journal entry items: 1st item: amount up to the legal limit, 2nd item: amount above the legal limit.
| [61] entry_id | [64] Entry Transaction Date | [70] Vendor Name | [63] Expense Type | [68] Is Personal | [62] Entry Transaction Type | [163] Payer Payment Type | [165] Payee Payment Type | [169] Journal Amount | [168] Debit Credit | [167] Account Code | [177] Cash Advance Amount | [185] Cash Advance Transaction Type |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 4196 | 5/28/2019 | - | Fixed Meals | N | REG | COMPANY | EMPLOYEE | 24 EUR | DR | 474230 | - | - |
| 4197 | 5/28/2019 | - | Fixed Meals | N | REG | COMPANY | EMPLOYEE | 26 EUR | DR | 474230 | - | - |
VAT Handling
Expense Posting With Single Tax Item
For the expense line: The Payer in this instance is the company; the Payee is the employee. Since it is not an itemized expense the Entry Transaction Type is REG. Because it is a legitimate business expense the ‘Is Personal’ flag is set to ‘N’. The employee will be reimbursed for this transaction. The Tax Code will also appear on this detail line along with the Tax Authority details (label and name).
Tax data: The appearance of the tax data in the extract is governed by the extract options to either include tax information in the same detail line as the entry on which tax is calculated, or to include it as a separate journal line. In this example tax is set to appear as a journal line. The payer is the notional tax authority with the payee as the company (as the reclaimed tax will eventually be paid by the tax authority to the company).
The Journal Amount on the tax detail line can be set to either list the amount eligible to reclaim on either the posted or adjusted (reclaim_posted_amount or reclaim_adjusted_amount). If ‘Adjusted’ the tax reclaim will be calculated on the approved amount (the approved amount may be lower than the claimed (posted) amount). The Tax Source identifies the source of the tax calculation.
The Tax Code can also be set to appear in the Account Code field on the tax detail line (instead of the account code), as shown in this example. The difference between the ‘reclaim’ fields (reclaim_tax_amount, reclaim_posted_amount, reclaim_adjusted_amount) and other tax amount fields (tax_amount, tax_posted_amount, etc.) is that ‘Reclaim’ indicates that these figures are subject to the reclaim percentage specified in the tax configuration.
| [61] entry_id | [64] Entry Transaction Date | [63] Expense Type | [68] Is Personal | [62] Entry Transaction Type | [163] Payer Payment Type | [165] Payee Payment Type | [169] Journal Amount | [168] Debit Credit | [167] Account Code | [226] Tax Auth Label | [227] Tax Amount | [228] Tax Posted Amount | [229] Tax Source | [230] reclaim_tax_amount | [231] reclaim_posted_amount | [232] Tax Code | [233] reclaim_domestic |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 4282 | 6/5/2019 | Laundry | N | REG | EMPLOYEE | COMPANY | 8.40 EUR | DR | 37 | ILR | 0 | 0 | - | 0 | 0 | V1 | - |
| 4282 | 6/5/2019 | Laundry | N | REG | ILR | COMPANY | 1.60 EUR | CR | V1 | ILR | 1.60 | 1.60 | SYST | 1.60 | 1.60 | V1 | Y |
Itemization
Itemized Expense Items
The Payer in this instance is the company; the Payee is the corporate card vendor. Since it is an itemized expense the Entry Transaction Type is CHD. Because it is a legitimate business expense the ‘Is Personal’ flag is set to ‘N’. Because this is an IBCP transaction and the payment will be made to the card vendor on behalf of the employee the employee will not receive reimbursement.
| [61] entry_id | [64] Entry Transaction Date | [70] Vendor Name | [63] Expense Type | [68] Is Personal | [62] Entry Transaction Type | [163] Payer Payment Type | [165] Payee Payment Type | [169] Journal Amount | [168] Debit Credit | [167] Account Code | [177] Cash Advance Amount | [185] Cash Advance Transaction Type |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 4199 | 05/27/2019 | All Suites International | Hotel Room Rate | N | CHD | COMPANY | IBCP CORP | USD 250 | DR | 474230 | - | - |
| 4200 | 05/27/2019 | All Suites International | Hotel Tax | N | CHD | COMPANY | IBCP CORP | USD 50 | DR | 474230 | - | - |
| 4201 | 05/28/2019 | All Suites International | Breakfast | N | CHD | COMPANY | IBCP CORP | USD 25 | DR | 474230 | - | - |
Cash Advances
Paid Cash
Issuance Extract (For reference only. Issuance is not included in the Expense Report FI Document)
There will be one issuance record for each cash advance issued. The issuance record can be identified by the Cash Advance Transaction Type which will always be a ‘1’. The Payer is the Company and the Payee is the Employee. The Journal Amount is a DR transaction in the reimbursement currency. The Cash Advance Amount is the amount of the cash advance in the currency of issuance. The Account Code is the employee cash advance account code, which is an element of the employee profile.
| [61] entry_id | [64] Entry Transaction Date | [70] Vendor Name | [63] Expense Type | [68] Is Personal | [62] Entry Transaction Type | [163] Payer Payment Type | [165] Payee Payment Type | [169] Journal Amount | [168] Debit Credit | [167] Account Code | [177] Cash Advance Amount | [185] Cash Advance Transaction Type |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| - | 3/7/2019 | - | - | N | - | COMPANY | EMPLOYEE | USD 7000 | DR | 1009990 | USD 7000 | 1 |
Cash Advance Is Lower Than the Payout Amount
Issuance Extract (For reference only. Issuance is not included in the Expense Report FI Document)
There will be one issuance record for each cash advance issued. The issuance record can be identified by the Cash Advance Transaction Type which will always be a ‘1’. The Payer is the Company and the Payee is the Employee. The Journal Amount is a DR transaction in the reimbursement currency. The Cash Advance Amount is the amount of the cash advance in the currency of issuance. The Account Code is the employee cash advance account code, which is an element of the employee profile.
| [61] entry_id | [64] Entry Transaction Date | [70] Vendor Name | [63] Expense Type | [68] Is Personal | [62] Entry Transaction Type | [163] Payer Payment Type | [165] Payee Payment Type | [169] Journal Amount | [168] Debit Credit | [167] Account Code | [177] Cash Advance Amount | [185] Cash Advance Transaction Type |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| - | 6/22/2019 | - | - | N | - | COMPANY | EMPLOYEE | GBP 300 | DR | - | GBP 300 | 1 |
The application of the CA issuance:
The application phase of this case will spawn five records in the standard extract file. Three of the records will cover the three cash out-of-pocket transactions. These three transactions are handled in the same way all cash, out-of-pocket transactions are handled (See the posting record above).
The two additional records are unique to an expense report containing a cash advance. The system will attempt to recover the cash advance amount from the employee by creating credit records against the cash transactions until the total of the cash advance is recovered. In this example, the first cash advance record (entry_id 61) credits the entire GBP 245 of its companion record (entry_id 58). That still leaves GBP 55 of the cash advance unrecovered. So another credit record (entry_id 62) in the amount of GBP 55 will be created against the next companion cash expense record (entry_id 59 and 60). At this point the GBP 300 cash advance has been recovered. The credit journal amounts have the effect of offsetting the total amount due the employee by the amount of the cash advance.
These offset records will have the following characteristics: the Payer is the employee; the Payee is the company. The debit/credit indicator will always be ‘CR’. The Cash Advance Amount field will always contain the total of the cash advances applied to the expense report. The Cash Advance Transaction Type will be a ‘2’. The employee will receive the net of the total cash expenses less the cash advance amount; in this example, GBP 15.
| [61] entry_id | [64] Entry Transaction Date | [70] Vendor Name | [63] Expense Type | [68] Is Personal | [62] Entry Transaction Type | [163] Payer Payment Type | [165] Payee Payment Type | [169] Journal Amount | [168] Debit Credit | [167] Account Code | [177] Cash Advance Amount | [185] Cash Advance Transaction Type |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 58 | 6/21/2019 | null | Rental Car | N | REG | COMPANY | EMPLOYEE | GBP 245 | DR | 109 | - | - |
| 59 | 6/21/2019 | Qdoba | Dinner | N | REG | COMPANY | EMPLOYEE | GBP 60 | DR | 105 | - | - |
| 60 | 6/21/2019 | Republic Parking | Parking | N | REG | COMPANY | EMPLOYEE | GBP 10 | DR | 130 | - | - |
| 61 | 6/21/2019 | - | Rental Car | N | REG | EMPLOYEE | COMPANY | GBP -245 | CR | 1009990 | GBP 300 | 2 |
| 62 | 6/21/2019 | - | Dinner & Parking | N | REG | EMPLOYEE | COMPANY | GBP -55 | CR | 1009990 | GBP 300 | 2 |
Cash Advance Is Higher Than the Payout Amount
Issuance Extract (For reference only. Issuance is not included in the Expense Report FI Document)
There will be one issuance record for each cash advance issued. The issuance record can be identified by the Cash Advance Transaction Type which will always be a ‘1’. The Payer is the company and the Payee is the employee. The Journal Amount is a DR transaction in the reimbursement currency. The Cash Advance Amount is the amount of the cash advance in the currency of issuance. The Account Code is the employee cash advance account code, which is an element of the employee profile.
| [61] entry_id | [64] Entry Transaction Date | [70] Vendor Name | [63] Expense Type | [68] Is Personal | [62] Entry Transaction Type | [163] Payer Payment Type | [165] Payee Payment Type | [169] Journal Amount | [168] Debit Credit | [167] Account Code | [177] Cash Advance Amount | [185] Cash Advance Transaction Type |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| - | 6/22/2019 | - | - | N | - | COMPANY | EMPLOYEE | GBP 400 | DR | - | GBP 300 | 1 |
The application of the CA issuance:
The application phase of this case will spawn seven records in the standard extract file. Three of the records will cover the three cash out-of-pocket transactions. These three transactions are handled in the same way all cash, out-of-pocket transactions are handled (See the posting record above).
The four additional records are unique to an expense report containing a cash advance. The system will attempt to recover the cash advance amount from the employee by creating credit records against the cash transactions until the total of the cash advance is recovered. In this example, since the total of all expenses does not equal or exceed the cash advance amount, all three expense records have a corresponding offset credit. That still leaves the user GBP 85 short. The cash advance return record in the amount of a GBP 85 credit nets the cash advance amount to zero.
These offset records will have the following characteristics: the Payer is the employee; the Payee is the company. The debit/credit indicator will always be ‘CR’. The Cash Advance Amount field will always contain the total of the cash advances applied to the expense report. The Cash Advance Transaction Type will be a ‘2’. The employee will receive the net of the total cash expenses less the cash advance amount and in the case of a net due to company the employee will be required to submit a cash advance return to retire the balance owed; in this example, GBP 85.
| [61] entry_id | [64] Entry Transaction Date | [70] Vendor Name | [63] Expense Type | [68] Is Personal | [62] Entry Transaction Type | [163] Payer Payment Type | [165] Payee Payment Type | [169] Journal Amount | [168] Debit Credit | [167] Account Code | [177] Cash Advance Amount | [185] Cash Advance Transaction Type |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 61 | 6/21/2019 | AVIS | Rental Car | N | REG | COMPANY | EMPLOYEE | GBP 245 | DR | 109 | - | - |
| 62 | 6/21/2019 | MORTONS | Business Meal | N | REG | COMPANY | EMPLOYEE | GBP 60 | DR | 105 | - | - |
| 63 | 6/21/2019 | Republic Parking | Parking | N | REG | COMPANY | EMPLOYEE | GBP 10 | DR | 130 | - | - |
| - | 6/21/2019 | AVIS | Rental Car | N | REG | EMPLOYEE | COMPANY | GBP -245 | CR | 1009990 | GBP 400 | 2 |
| - | 6/21/2019 | MORTONS | Business Meal | N | REG | EMPLOYEE | COMPANY | GBP -60 | CR | 1009990 | GBP 400 | 2 |
| - | 6/21/2019 | Republic Parking | Parking | N | REG | EMPLOYEE | COMPANY | GBP -10 | CR | 1009990 | GBP 400 | 2 |
| - | 6/21/2019 | - | Cash Advance Return | N | REG | EMPLOYEE | COMPANY | GBP -85 | CR | 1009990 | GBP 400 | 2 |
Credit Card Types
Payment via Employee Vendor Account
The Payer in this instance is the company; the Payee is the employee. Since it is not an itemized expense the Entry Transaction Type is REG. Because it is a legitimate business expense the ‘Is Personal’ flag is set to ‘N’. The employee will be reimbursed for this transaction.
| [61] entry_id | [64] Entry Transaction Date | [70] Vendor Name | [63] Expense Type | [68] Is Personal | [62] Entry Transaction Type | [163] Payer Payment Type | [165] Payee Payment Type | [169] Journal Amount | [168] Debit Credit | [167] Account Code | [177] Cash Advance Amount | [185] Cash Advance Transaction Type |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 8337 | 03/05/2016 | - | Taxi | N | REG | COMPANY | EMPLOYEE | USD 10 | DR | 474230 | - | - |
Payment via Credit Card Vendor Account (Split Payment)
The Payer in this instance is the company; the Payee is the corporate card vendor. Since it is not an itemized expense the Entry Transaction Type is REG. Because it is a legitimate business expense the ‘Is Personal’ flag is set to ‘N’. Because this is an IBCP transaction and the payment will be made to the card vendor on behalf of the employee the employee will not receive reimbursement.
| [61] entry_id | [64] Entry Transaction Date | [70] Vendor Name | [63] Expense Type | [68] Is Personal | [62] Entry Transaction Type | [163] Payer Payment Type | [165] Payee Payment Type | [169] Journal Amount | [168] Debit Credit | [167] Account Code | [177] Cash Advance Amount | [185] Cash Advance Transaction Type |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 36 | 4/7/2008 | DOLLAR | Rental Car | N | REG | COMPANY | IBCP CORP | USD 56.10 | DR | 11 | - | - |
Credit Transaction via Credit Card Vendor Account (Split Payment)
The Payer in this instance is the corporate card vendor; the Payee is the company. Since it is not an itemized expense the Entry Transaction Type is REG. Because it is a legitimate business expense the ‘Is Personal’ flag is set to ‘N’. Because this is an IBCP transaction and the payment/credit will be made to the card vendor on behalf of the employee the employee will not receive reimbursement (or be required to pay the balance).
| [61] entry_id | [64] Entry Transaction Date | [70] Vendor Name | [63] Expense Type | [68] Is Personal | [62] Entry Transaction Type | [163] Payer Payment Type | [165] Payee Payment Type | [169] Journal Amount | [168] Debit Credit | [167] Account Code | [177] Cash Advance Amount | [185] Cash Advance Transaction Type |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 4225 | 5/27/2019 | ALASKA AIRLINE | Airfare | N | REG | COPD | COMPANY | USD -349 | CR | 474230 | - | - |
Simple IBCP Corporate Card Charge With Itemization
The Payer in this instance is the company; the Payee is the corporate card vendor. Since it is an itemized expense the Entry Transaction Type is ‘CHD’. Because it is a legitimate business expense the ‘Is Personal’ flag is set to ‘N’. Because this is an IBCP transaction and the payment will be made to the card vendor on behalf of the employee the employee will not receive reimbursement.
| [61] entry_id | [64] Entry Transaction Date | [70] Vendor Name | [63] Expense Type | [68] Is Personal | [62] Entry Transaction Type | [163] Payer Payment Type | [165] Payee Payment Type | [169] Journal Amount | [168] Debit Credit | [167] Account Code | [177] Cash Advance Amount | [185] Cash Advance Transaction Type |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 4199 | 05/27/2019 | All Suites International | Hotel Room Rate | N | CHD | COMPANY | IBCP CORP | USD 250 | DR | 474230 | - | - |
| 4200 | 05/27/2019 | All Suites International | Hotel Tax | N | CHD | COMPANY | IBCP CORP | USD 50 | DR | 474230 | - | - |
| 4201 | 05/28/2019 | All Suites International | Breakfast | N | CHD | COMPANY | IBCP CORP | USD 25 | DR | 474230 | - | - |
IBCP With Personal Expense: No Out-of-Pocket
The Payer in this instance is the company; the Payee is the corporate card vendor. Since it is an itemized expense the Entry Transaction Type is CHD. Because this is an IBCP transaction and the payment will be made to the card vendor on behalf of the employee the employee will not receive reimbursement. Because the entry marked as personal is not a legitimate/approved business expense, payment to the card vendor is the responsibility of the employee. The amount is not reimbursable to the employee and the expense amount should not be posted with other business transactions. Therefore, the personal amount is not included in the financial posting JSON.
| [61] entry_id | [64] Entry Transaction Date | [70] Vendor Name | [63] Expense Type | [68] Is Personal | [62] Entry Transaction Type | [163] Payer Payment Type | [165] Payee Payment Type | [169] Journal Amount | [168] Debit Credit | [167] Account Code | [177] Cash Advance Amount | [185] Cash Advance Transaction Type |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 4220 | 05/29/2019 | All Suites International | Hotel Room Rate | N | CHD | COMPANY | IBCP | USD 250 | DR | 474230 | - | - |
| 4221 | 05/29/2019 | All Suites International | Hotel Tax | N | CHD | COMPANY | IBCP | USD 50 | DR | 474230 | - | - |
| 4222 | 05/30/2019 | All Suites International | Breakfast | Y | REG | EMPL | COMPANY | USD 25 | DR | 199999 | - | - |
IBCP with Personal Expense Where Out-of-Pocket Exceeds the Personal Expense
The Payer for both transactions is the company. The Payee is the corporate card vendor for the legitimate business expenses on the hotel transaction (the hotel expenses and the dinner expense). Because the reimbursement method is IBCP w/offsets, the card vendor will also be the payee for the personal expenses on the hotel transaction up to the total amount of out-of-pocket cash expense submitted on this expense report. Since the non-reimbursable in-room movie expense (USD 14) is less than the total out-of-pocket cash expenses (USD 35) owed to the employee, the company will pay the USD 14 personal expense to the card vendor and offset that amount against the USD 35 owed to the employee. Thus the employee will only receive USD 21 of the USD 35 taxi expense. In this case there were enough out-of-pocket cash expenses to offset the non-reimbursable expenses so there is a net due to the employee for this expense report.
| [61] entry_id | [64] Entry Transaction Date | [70] Vendor Name | [63] Expense Type | [68] Is Personal | [62] Entry Transaction Type | [163] Payer Payment Type | [165] Payee Payment Type | [169] Journal Amount | [168] Debit Credit | [167] Account Code | [177] Cash Advance Amount | [185] Cash Advance Transaction Type |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 89 | 7/15/2019 | MARRIOTT | Hotel | N | CHD | COMPANY | IBCP CORP | USD 125 | DR | 99999 | - | - |
| 90 | 7/16/2019 | MARRIOTT | Hotel | N | CHD | COMPANY | IBCP CORP | USD 125 | DR | 99999 | - | - |
| 91 | 7/15/2019 | MARRIOTT | Dinner | N | CHD | COMPANY | IBCP CORP | USD 20 | DR | 600 | - | - |
| 93 | 7/16/2019 | Taxi | Local Trans | N | REG | COMPANY | EMPLOYEE | USD 21 | DR | 88888 | - | - |
| 93 | 7/16/2019 | Taxi | Local Trans | N | REG | COMPANY | IBCP CORP | USD 14 | DR | 88888 | - | - |
IBCP With Personal Expense Where Out-of-Pocket Is Less Than Personal Expense
The Payer for both transactions is the company. The Payee is the corporate card vendor for the legitimate business expenses on the Hotel transaction (the Hotel expenses and the Dinner expense). Because the reimbursement method is IBCP w/offsets, the card vendor will also be the payee for the personal expenses on the Hotel transaction up to the total amount of out-of-pocket cash expense submitted on this expense report. Since the non-reimbursable in-room movie expense (USD 14) is greater than the total out-of-pocket cash expenses (USD 5) owed to the employee, the company will pay only USD 5 of the USD 14 personal expense to the card vendor and offset that amount against the USD 5 owed to the employee. Thus the employee will not receive any reimbursement and will personally owe the card vendor for the difference between the USD 5 paid by the company on his behalf and the USD 14 charge, or USD 9. In this case there were not enough out-of-pocket cash expenses to offset the non-reimbursable expenses so the employee is responsible to make up the difference with the card vendor.
| [61] entry_id | [64] Entry Transaction Date | [70] Vendor Name | [63] Expense Type | [68] Is Personal | [62] Entry Transaction Type | [163] Payer Payment Type | [165] Payee Payment Type | [169] Journal Amount | [168] Debit Credit | [167] Account Code | [177] Cash Advance Amount | [185] Cash Advance Transaction Type |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 95 | 7/15/2019 | MARRIOTT | Hotel | N | CHD | COMPANY | IBCP CORP | USD 125 | DR | 99999 | - | - |
| 98 | 7/16/2019 | MARRIOTT | Hotel | N | CHD | COMPANY | IBCP CORP | USD 125 | DR | 99999 | - | - |
| 96 | 7/16/2019 | MARRIOTT | Dinner | N | CHD | COMPANY | IBCP CORP | USD 20 | DR | 600 | - | - |
| 99 | 7/16/2019 | PARKING | Parking | N | REG | COMPANY | IBCP CORP | USD 5 | DR | 40 | - | - |
CBCP Corporate Card Charge for Entirely Personal Expense (Net Due Company With Consolidated or Verbose Extract)
The extract produces two records for this single transaction. One record addresses payment that must be made to the card vendor by the company. The Payer is the company. The Payee is the corporate card vendor. The amount is a debit of USD 49 to the clearing account. Since there are no employee out-of-pocket expenses on this expense report there is nothing to offset the amount that the employee owes the company. Therefore, a separate record is created to address the net due company condition. In this record the Payer is the employee and the Payee is the company. The amount is a credit of USD 49 to the clearing account. The company’s financial system must have a process for dealing with this employee receivable condition. The CT&E system will not “carry over” this net due company amount to subsequent expense reports.
The company will pay the credit card vendor for the full amount due the card and retain a corresponding employee receivable (most likely represented as a debit in the employee’s vendor account. This allows natural offsetting to occur if there are subsequent amounts due the employee posted to their vendor record in the future.
| [61] entry_id | [64] Entry Transaction Date | [70] Vendor Name | [63] Expense Type | [68] Is Personal | [62] Entry Transaction Type | [163] Payer Payment Type | [165] Payee Payment Type | [169] Journal Amount | [168] Debit Credit | [167] Account Code | [177] Cash Advance Amount | [185] Cash Advance Transaction Type |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| - | 6/1/2016 | - | Dues | Y | REG | EMPLOYEE | COMPANY | USD -49 | CR | cbcp180 | - | - |
| - | 6/1/2016 | - | Dues | Y | REG | COMPANY | CBCP CORP | USD 49 | DR | cbcp180 | - | - |
| - | 6/1/2016 | - | Tolls | Y | REG | EMPLOYEE | COMPANY | USD -32 | CR | compaid374 | - | - |
| - | 6/1/2016 | - | Tolls | Y | REG | COMPANY | CBCP CORP | USD 32 | DR | compaid374 | - | - |
CBCP Corporate Card Charge with Itemization and Personal Expense (Net Due Employee With Consolidation)
The Payer for both transactions is the company. The Payee is the corporate card vendor for the full amount of the hotel transaction (the company owes the card vendor for the entire amount of the transaction, including the non-reimbursable in-room movie) and the employee for the balance of the taxi expense after the offset is taken for the in-room movie portion of the corporate card transaction. The employee would normally be reimbursed for the full USD 35 out-of-pocket taxi expense but, because a portion of the company paid corporate card transaction was not a legitimate business expense, the system reduces the amount due to the employee by the amount of the non-reimbursable expense. In this case there was enough out-of-pocket cash expenses to offset the non-reimbursable expenses so there is a net due to the employee for this expense report.
| [61] entry_id | [64] Entry Transaction Date | [70] Vendor Name | [63] Expense Type | [68] Is Personal | [62] Entry Transaction Type | [163] Payer Payment Type | [165] Payee Payment Type | [169] Journal Amount | [168] Debit Credit | [167] Account Code | [177] Cash Advance Amount | [185] Cash Advance Transaction Type |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 4252 | 6/4/2019 | MARRIOTT | Hotel | N | CHD | COMPANY | CBCP CORP | USD 125 | DR | 474230 | - | - |
| 4253 | 6/3/2019 | MARRIOTT | Hotel | N | CHD | COMPANY | CBCP CORP | USD 125 | DR | 7271001 | - | - |
| 4254 | 6/3/2019 | MARRIOTT | Dinner | N | CHD | COMPANY | CBCP CORP | USD 20 | DR | 474230 | - | - |
| 4291 | 5/29/2019 | Taxi | Local Trans | N | REG | COMPANY | EMPLOYEE | USD 35 | DR | 474230 | - | - |
| 4255 | 6/5/2019 | MARRIOTT | In-room movie | Y | REG | COMPANY | CBCP CORP | USD 14 | DR | 199999 | - | - |
CBCP Corporate Card Charge for Entirely Personal Expense (Net Due Company With Verbose Extract)
The extract produces two records for this single transaction. One record addresses payment that must be made to the card vendor by the company. The Payer is the company. The Payee is the corporate card vendor. The amount is a debit of USD 300 to the clearing account. The second record is created to address the net due company condition. In this record the Payer is the employee and the Payee is the company. The amount is a credit of USD 300 to the clearing account. The company’s financial system must have a process for dealing with this employee receivable condition. The CT&E system will not “carry over” this net due company amount to subsequent expense reports.
| [61] entry_id | [64] Entry Transaction Date | [70] Vendor Name | [63] Expense Type | [68] Is Personal | [62] Entry Transaction Type | [163] Payer Payment Type | [165] Payee Payment Type | [169] Journal Amount | [168] Debit Credit | [167] Account Code | [177] Cash Advance Amount | [185] Cash Advance Transaction Type |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| - | 9/1/2016 | Cheesecake Factory | Dinner | Y | REG | EMPLOYEE | COMPANY | USD -300 | CR | - | - | - |
| - | 9/1/2016 | Cheesecake Factory | Dinner | Y | REG | COMPANY | CBCP CORP | USD 300 | DR | - | - | - |
CBCP Corporate Card Charge with Itemization and Personal Expense (Net Due Employee With No Offsets)
The records are slightly different from the previous example where offsets are built into the extract. In this case, where there are no built-in offsets, each record is distinct and the offset will need to be calculated in the client’s bridge program. The Payer for both transactions is the company except for the personal portion of the Hotel expense. The personal amount of USD 14 is represented with two distinct records. One record addresses the amount due to the corporate card vendor to ensure that the full amount of the otel transaction (including the personal amount) is paid to the card vendor. A second offsetting record addresses the same personal amount that the employee owes back to the company. In the first record, the company is the Payer and the Payee is the corporate card vendor for the USD 14 non-reimbursable in-room movie). In the second record the employee is the Payer and the Payee is the company for the credit amount of the USD 14 non-reimbursable in-room movie. The full USD 35 out-of-pocket taxi expense is handled as a normal out-of-pocket cash expense with the company being the Payer and the employee being the Payee. The client’s bridge program will need to summarize the two records (+USD 35 taxi and -USD 14 in-room movie) to arrive at the USD 21 due to the employee.
| [61] entry_id | [64] Entry Transaction Date | [70] Vendor Name | [63] Expense Type | [68] Is Personal | [62] Entry Transaction Type | [163] Payer Payment Type | [165] Payee Payment Type | [169] Journal Amount | [168] Debit Credit | [167] Account Code | [177] Cash Advance Amount | [185] Cash Advance Transaction Type |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 4336 | 6/6/2019 | MARRIOTT | Hotel | N | CHD | COMPANY | CBCP CORP | USD 125 | DR | 474230 | - | - |
| 4337 | 6/7/2019 | MARRIOTT | Hotel | N | CHD | COMPANY | CBCP CORP | USD 125 | DR | 474230 | - | - |
| 4338 | 6/8/2019 | MARRIOTT | Dinner | N | CHD | COMPANY | CBCP CORP | USD 20 | DR | 474230 | - | - |
| 4339 | 6/8/2019 | MARRIOTT | In-Room Movie | Y | CHD | COMPANY | CBCP CORP | USD 14 | DR | 199999 | - | - |
| 4339 | 6/8/2019 | MARRIOTT | In-Room Movie | Y | CHD | EMPLOYEE | COMPANY | USD 14 | CR | 199999 | - | - |
| 4340 | 6/8/2019 | Taxi | Local Trans | N | REG | COMPANY | EMPLOYEE | USD 35 | DR | 474230 | - | - |
Financial Integration Service v4 - Getting Started
The Financial Integration API allows an external system to interact with financial documents generated from SAP Concur, for financial posting into an ERP.
This API provides an automated solution to request available data objects such as approved expense reports, cash advances, and invoices to import to the client internal system, with an opportunity to send posting confirmation back into SAP Concur before the object is locked down and cannot be altered in SAP Concur.
Below are some benefits for using the Financial Integration service:
- Using a modern method, no more handling of flat files.
- Close to real time experience vs. SAP Concur overnight processing.
- 1 to 1 SAP Concur to ERP reconciliation vs. extract batch processing.
- Opportunity to modify and retry before the object is locked in SAP Concur.
- Ensures data sync between systems.
Limitations: This API is available to both customers and partners who have been granted access by SAP Concur. Invoice Standard customers should reach out to their SAP Concur representative to receive more information on implementation. Access to this documentation does not provide access to the API. The API is available in North America, EMEA, and China Production and Implementation environments.
Getting Started
- Products and Editions
- Scope Usage
- Access Token Usage
- Get Financial Transactions
- Post Financial Transactions Acknowledgements
- Post Financial Transactions Confirmations
- Post Financial Payment Confirmations
- Service Codes
- Schema
- Financial Documents
- FIDocument
- Page Metadata
- Link
- AcknowledgeRequest
- AcknowledgeResponse
- AcknowledgeResponseItem
- Confirmation Request
- Posting Confirmation Request Item
- Posting Documents Details
- System Messages
- Posting Confirmation Response
- PostingConfirmationResponseItem
- Payment Confirmation Request
- Payment Confirmation Request Item
- Payment Documents Details
- Receiver Details
- Clearing Reference Details
- Payment Confirmation Response
- PaymentConfirmationResponseItem
- Examples
Products and Editions
- Concur Expense Professional Edition
- Concur Expense Standard Edition
- Concur Invoice Professional Edition
- Concur Invoice Standard Edition
Scope Usage
| Name | Description | Endpoint |
|---|---|---|
FISVC |
Read financial transactions and write financial transaction acknowledgements and confirmations. | GET, POST |
Access Token Usage
This API only supports company-level access tokens.
Get Financial Transactions
The request returns a list of financial documents that are ready to be processed. The request can include parameters to limit the results.
Scopes
FISVC - Refer to Scope Usage for full details.
Request
URI
Template
https://{datacenterURI}/financialintegration/fi/v4/companies/transactiontypes/{docType}/transactions
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
docType |
string |
path |
Required The financial document type to return. Only one type of transaction can be retrieved at a time. Supported values are: expense, invoice, cashadvance, payroll, obligation. |
page |
int32 |
query |
Starting page number. |
limit |
int32 |
query |
Number of records to return per page. Default: 25. |
docId |
string |
query |
The transaction unique identifier, it could be expense report ID, payment request ID or cash advance ID. If specified, a single document that matches docId is returned. |
ignoreDocumentStatus |
string |
query |
Ignores the financial documents status. If yes, a document is returned regardless of status. If no, only documents that have not been acknowledged/confirmed are returned. Supported values: yes, no. (See note below) |
systemId |
string |
query |
The external system ID that processed the document. Maximum 50 characters. |
Note The
ignoreDocumentStatusparameter is useful for Universal (Standard Edition) customers who are using a Test ERP with a production SAP Concur expense report (Universal customers don't have SAP Concur test sites or Test User functionality, so real reports are used for testing). Once the test is confirmed, the partner can call the report again so they can post into the production ERP.
Headers
- DocumentFormatAs: Value can be text or JSON. This determines the document format that's returned from the API.
- RFC 7235 Authorization - Bearer token that identifies the caller. This is the Company access token.
Payload
None.
Response
Status Codes
Headers
concur-correlationidis an SAP Concur specific custom header used for technical support in the form of a RFC 4122 universally unique identifier (UUID) URN Namespace.- RFC 7231 Content-Type
- RFC 7230 Content-Length
Payload
Example
Request
GET https://us.api.concursolutions.com/financialintegration/fi/v4/companies/transactiontypes/expense/transactions?limit=3
Authorization: Bearer {token}
Response
200 OK
Content-Type: application/json
Date: {date-requested}
Content-Length: 491
{
"links" : [ {
"rel" : "first",
"href" : "https://fiserviceurlhere/fi/v4/companies/transactiontypes/expense/transactions?limit=3&page=0&size=3",
"hreflang" : null,
"media" : null,
"title" : null,
"type" : null,
"deprecation" : null
}, {
"rel" : "self",
"href" : "https://fiserviceurlhere/fi/v4/companies/transactiontypes/expense/transactions?limit=3&page=0&size=3",
"hreflang" : null,
"media" : null,
"title" : null,
"type" : null,
"deprecation" : null
}, {
"rel" : "next",
"href" : "https://fiserviceurlhere/fi/v4/companies/transactiontypes/expense/transactions?limit=3&page=1&size=3",
"hreflang" : null,
"media" : null,
"title" : null,
"type" : null,
"deprecation" : null
}, {
"rel" : "last",
"href" : "https://fiserviceurlhere/fi/v4/companies/transactiontypes/expense/transactions?limit=3&page=2&size=3",
"hreflang" : null,
"media" : null,
"title" : null,
"type" : null,
"deprecation" : null
} ],
"content" : [ {
"id" : "e7f810cabc8348cdb051dd9431c8cfbb",
"docType" : "expense",
"companyId" : "COMPANY_ID_HERE",
"entityId" : "ENTITY_ID_HERE",
"companyUuid" : "COMPANY_UUID_HERE",
"erpSystemId" : "",
"document" : "{THE_FINANCIAL_DOCUMENT}",
"docStatus" : "READY",
"links" : [ ]
}, {
"id" : "e1500222f16748718fdd2d493ee4c9dd",
"docType" : "expense",
"companyId" : "COMPANY_ID_HERE",
"entityId" : "ENTITY_ID_HERE",
"companyUuid" : "COMPANY_UUID_HERE",
"erpSystemId" : null,
"document" : "{THE_FINANCIAL_DOCUMENT}",
"docStatus" : "READY",
"links" : [ ]
}, {
"id" : "e2135678f16748718fdd2d493ee4c9dd",
"docType" : "expense",
"companyId" : "COMPANY_ID_HERE",
"entityId" : "ENTITY_ID_HERE",
"companyUuid" : "COMPANY_UUID_HERE",
"erpSystemId" : null,
"document" : "{THE_FINANCIAL_DOCUMENT}",
"docStatus" : "READY",
"links" : [ ]
}
],
"page" : {
"size" : 3,
"totalElements" : 8,
"totalPages" : 3,
"number" : 0
}
}
Post Financial Transaction Acknowledgements
Allows an external system to acknowledge that it has successfully retrieved one or more financial transactions from SAP Concur and will begin processing those transactions. The transactions in the POST request are then taken out of the ready queue.
An app should execute the POST request immediately after the GET request. Eliminating any time between the requests will avoid a variance between the ERP and SAP Concur. For example, if there is a time lag, the customer administrator could use the SAP Concur Processor tool to recall or send a report (or invoice) back to the report owner where he or she can change it or even delete it. This would create a discrepancy between SAP Concur and the ERP.
Scopes
FISVC - Refer to Scope Usage for full details.
Request
URI
Template
https://{datacenterURI}/financialintegration/fi/v4/companies/transactiontypes/{docType}/transactions/acknowledgements
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
docType |
string |
path |
Required The financial document type. Only one type of transaction can be acknowledged at a time. Supported values: expense, invoice, cashadvance, payroll, obligation. |
Headers
- RFC 7235 Authorization - Bearer token that identifies the caller. This is the Company access token.
- RFC 7231 Content-Type
Payload
Response
Status Codes
Headers
concur-correlationidis an SAP Concur specific custom header used for technical support in the form of a RFC 4122 universally unique identifier (UUID) URN Namespace.- RFC 7231 Content-Type
- RFC 7230 Content-Length
Payload
Example
Request
POST https://us.api.concursolutions.com/financialintegration/fi/v4/companies/transactiontypes/expense/transactions/acknowledgements
Authorization: Bearer {token}
Content-Type: application/json
{
"ids": [ "5ab9224e02e840148e7cd7d9e8e72968", "2ac9224e02e840148e7cd7d9e8e12345" ]
}
Response
This response shows both success and failure service code examples.
200 OK
Content-Type: application/json
Date: {date-requested}
Content-Length: 372
[
{
"code": 0,
"docId": "5ab9224e02e840148e7cd7d9e8e72968",
"systemId": null,
"acknowledgeResult": "SUCCESS",
"errorMessage": ""
},
{
"code": 101,
"docId": "2ac9224e02e840148e7cd7d9e8e12345",
"systemId": null,
"acknowledgeResult": "FAILURE",
"errorMessage": "This document was previously acknowledged by SystemId: null."
}
]
Post Financial Transactions Confirmations
Allows financial posting results to be sent to SAP Concur.
Scopes
FISVC - Refer to Scope Usage for full details.
Request
URI
Template
https://{datacenterURI}/financialintegration/fi/v4/companies/transactiontypes/{docType}/transactions/postingconfirmations
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
docType |
string |
path |
Required The financial document type to return. Only one type of transaction can be retrieved at a time. Supported values: expense, invoice, cashadvance, payroll, obligation |
confirmationRequest |
- | body | Required The JSON request to be posted. |
Headers
- RFC 7235 Authorization - Bearer token that identifies the caller. This is the Company access token.
- RFC 7231 Content-Type
Payload
Response
Status Codes
Headers
concur-correlationidis an SAP Concur specific custom header used for technical support in the form of a RFC 4122 universally unique identifier (UUID) URN Namespace.- RFC 7231 Content-Type
- RFC 7230 Content-Length
Payload
Example
Request
POST https://us.api.concursolutions.com/financialintegration/fi/v4/companies/transactiontypes/expense/transactions/postingconfirmations
Authorization: Bearer {token}
Content-Type: application/json
{
"systemId":"",
"postingConfirmations":
[
{
"docId":"0c06ab044834454d91f83cbd7b6431d2",
"overallPostingStatusCode":"error",
"postingDocs":[],
"systemMessages":
[
{
"concurTransactionLineItemId":"",
"messageId":"010-CTE-POSTING",
"messageLanguage":"EN",
"messageLongText":"",
"messageShortText":"Expense Report {ReportKey} of system CONCUR could not be posted."
},
{
"concurTransactionLineItemId":"",
"messageId":"003-CC",
"messageLanguage":"EN",
"messageLongText":"",
"messageShortText":"Profit centre /company code assignment is not correct. Check the entry."
}
]
},
{
"docId":"3331dbeb8e2240ffad7ab5b69492722a",
"overallPostingStatusCode":"success",
"postingDocs":
[
{
"companyId":"0100",
"documentNumber":"0123456",
"fiscalYear":"2018",
"paymentRelevantLineItems":[],
"postingDate":"2018-03-02"
},
{
"companyId":"0800",
"documentNumber":"0123478",
"fiscalYear":"2018",
"paymentRelevantLineItems":[],
"postingDate":"2018-03-02"
}
],
"systemMessages":[]
}
]
}
Response
This response shows both success and failure service code examples.
200 OK
Content-Type: application/json
Date: {date-requested}
Content-Length: 405
[
{
"code": 0,
"docId": "0c06ab044834454d91f83cbd7b6431d2",
"systemId": null,
"postingConfirmationResult": "SUCCESS",
"errorMessage": "",
"detailMessage": ""
},
{
"code": 116,
"docId": "3331dbeb8e2240ffad7ab5b69492722a",
"systemId": "",
"postingConfirmationResult": "FAILURE",
"errorMessage": "This document does not exist.",
"detailMessage": ""
}
]
Post Financial Payment Confirmations
Allows financial payment results to be sent to SAP Concur.
Scopes
FISVC - Refer to Scope Usage for full details.
Request
URI
Template
https://{datacenterURI}/financialintegration/fi/v4/companies/transactiontypes/{docType}/transactions/paymentconfirmations
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
docType |
string |
path |
Required The financial document type to return. Only one type of transaction can be retrieved at a time. Supported values: expense, invoice, cashadvance, payroll, obligation |
confirmationRequest |
body | Required The JSON request to be posted. |
Headers
- RFC 7235 Authorization - Bearer token that identifies the caller. This is the Company access token.
- RFC 7231 Content-Type
Payload
Response
Status Codes
Headers
concur-correlationidis an SAP Concur specific custom header used for technical support in the form of a RFC 4122 universally unique identifier (UUID) URN Namespace.- RFC 7231 Content-Type
- RFC 7230 Content-Length
Payload
Example
Request
POST https://us.api.concursolutions.com/financialintegration/fi/v4/companies/transactiontypes/expense/transactions/paymentconfirmations
Authorization: Bearer {token}
Content-Type: application/json
{
"systemId":"",
"processingConfirmation":
[
{
"docId":"0c06ab044834454d91f83cbd7b6431d2",
"processingStatusCode":"CP",
"clearingDetails":[
{
"clearingDate":"2019-02-06T12:00:00.27Z","clearingAmount":220.00,
"clearingCurrency":"USD","receiver":{"receiverId":"22344",
"receiverName":"Charles","receiverType":"EMPLOYEE"},
"clearingReference":{"companyCode":"US01","financialDocumentId":"667799",
"fiscalYear":"2019","paymentRef":"US01/667799/2019/2","paymentMethod":"E"}
}
]
},
{
"docId":"454d91f83cbd7b6431d20c06ab044834",
"processingStatusCode":"PP",
"clearingDetails":[
{
"clearingDate":"2019-02-06T12:00:00.27Z","clearingAmount":40.00,
"clearingCurrency":"USD","receiver":{"receiverId":"57",
"receiverName":"John","receiverType":"EMPLOYEE"},
"clearingReference":{"companyCode":"US01","financialDocumentId":"996675",
"fiscalYear":"2019","paymentRef":"US01/996675/2019/2","paymentMethod":"E"}
}
]
},
{
"docId":"1d20c06ab0445d7b64348344d91f83cb",
"processingStatusCode":"PP",
"clearingDetails":[
{
"clearingDate":"2019-02-06T12:00:00.27Z","clearingAmount":23.00,
"clearingCurrency":"USD","receiver":{"receiverId":"57",
"receiverName":"Alice","receiverType":"EMPLOYEE"},
"clearingReference":{"companyCode":"US01","financialDocumentId":"95432",
"fiscalYear":"2019","paymentRef":"US01/95432/2019/2","paymentMethod":"E"}
}
]
},
{
"docId":"d2454d91fcb44834830c06ab0d7b6431",
"processingStatusCode":"RE",
"additionalMessage":"This report was sent to wrong system",
"clearingDetails":[
{
"clearingDate":"2019-02-06T12:00:00.27Z","clearingAmount":10.00,
"clearingCurrency":"USD","receiver":{"receiverId":"57",
"receiverName":"Peter","receiverType":"EMPLOYEE"},
"clearingReference":{"companyCode":"US01","financialDocumentId":"5498",
"fiscalYear":"2019","paymentRef":"US01/5498/2019/2","paymentMethod":"E"}
}
]
},
{
"docId":"b6431d2454dcbd791f44834830c06ab0",
"processingStatusCode":"OB",
"additionalMessage":"Not required anymore",
"clearingDetails":[
{
"clearingDate":"2019-02-06T12:00:00.27Z","clearingAmount":54.00,
"clearingCurrency":"USD","receiver":{"receiverId":"57",
"receiverName":"Kevin","receiverType":"EMPLOYEE"},
"clearingReference":{"companyCode":"US01","financialDocumentId":"32478",
"fiscalYear":"2019","paymentRef":"US01/32478/2019/2","paymentMethod":"E"}
}
]
}
]
}
Response
This response shows both success and failure service code examples.
200 OK
Content-Type: application/json
Date: {date-requested}
Content-Length: 405
[
{
"code" : 0,
"docId" : "0c06ab044834454d91f83cbd7b6431d2",
"systemId" : "",
"paymentConfirmationResult" : "SUCCESS",
"errorMessage" : null,
"paymentRef" : "US01/667799/2019/2",
"detailMessage" : ""
},
{
"code" : 116,
"docId" : "454d91f83cbd7b6431d20c06ab044834",
"systemId" : "",
"paymentConfirmationResult" : "FAILURE",
"errorMessage" : "This document does not exist.",
"paymentRef" : "US01/996675/2019/2",
"detailMessage" : ""
},
{
"code" : 298,
"docId" : "1d20c06ab0445d7b64348344d91f83cb",
"systemId" : "",
"paymentConfirmationResult" : "NOOP",
"errorMessage" : "Payment confirmation already exist US01/95432/2019/2.",
"paymentRef" : "US01/95432/2019/2",
"detailMessage" : ""
}
{
"code" : 0,
"docId" : "d2454d91fcb44834830c06ab0d7b6431",
"systemId" : "",
"paymentConfirmationResult" : "SUCCESS",
"errorMessage" : null,
"paymentRef" : "US01/5498/2019/2",
"detailMessage" : ""
},
{
"code" : 0,
"docId" : "b6431d2454dcbd791f44834830c06ab0",
"systemId" : "",
"paymentConfirmationResult" : "SUCCESS",
"errorMessage" : null,
"paymentRef" : "US01/32478/2019/2",
"detailMessage" : ""
}
]
Service Codes
The Financial Integration Service will return service codes based on the success and failure of individual records for acknowledging and posting confirmation of documents.
| Code | Description | Category |
|---|---|---|
| 0 | Successfully processed | Any |
| 99 | System ID in request does not match system ID in FI database. | Any |
| 101 | This document was previously acknowledged. | Acknowledge |
| 102 | This document has been recalled. | Acknowledge |
| 103 | This document is not ready. | Acknowledge |
| 104 | This document does not exist in the FI database. | Acknowledge |
| 105 | This document is not of type (expense, invoice, cashadvance). | Acknowledge |
| 111 | This document has not been acknowledged. | Posting |
| 112 | This document has been recalled. | Posting |
| 113 | Confirmation has been posted for this document. | Posting |
| 114 | Document is not in a known state. | Posting |
| 115 | This document is not of type (expense, invoice, cashadvance). | Posting |
| 116 | This document does not exist in the FI database. | Posting |
| 198 | Invalid request - this same request will not work if tried again. | Posting |
| 199 | Unknown error, please try again later. | Any |
Schema
Financial Documents
| Name | Type | Format | Description |
|---|---|---|---|
content |
Array |
FIDocument | The result collection. |
page |
string |
PageMetadata | Pagination details. |
links |
Array |
Link | Pagination links. |
FIDocument
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
- | The unique identifier for the document. |
docType |
string |
- | Transaction type. Supported values: expense, invoice, cashadvance, payroll, obligation. |
companyId |
string |
- | Unique identifier for the company in SAP Concur. Maximum 32 characters. |
entityId |
string |
- | Unique identifier for the entity in SAP Concur. Maximum 32 characters. |
companyUuid |
string |
UUID |
UUID for the company in SAP Concur. Maximum 36 characters. |
erpSystemId |
string |
- | The external System ID that processed the document. Maximum 50 characters. |
document |
Array |
- | The JSON financial document. Review the FI sample documents below. |
docStatus |
string |
- | The financial document status. Supported values: READY, ACKNOWLEDGED, POSTING_CONFIRMED_SUCCESS, POSTING_CONFIRMED_FAILURE. |
PageMetadata
| Name | Type | Format | Description |
|---|---|---|---|
size |
int32 | - | Total number of pages returned. |
totalElements |
int32 | - | Total count of records returned. |
totalPages |
int32 | - | Total number of pages returned. |
number |
int32 | - | Page location for which the result is returned, for example: first page starts with 0, second page starts with 1. |
Link
| Name | Type | Format | Description |
|---|---|---|---|
rel |
string |
- | Relation of link, for example: first, self, next, last. |
href |
string |
- | Complete URL for the paginated link. |
hreflang |
string |
- | Link language, if any. |
media |
string |
- | Media type, if any. |
title |
string |
- | Link title, if any. |
type |
string |
- | Link type, if any. |
deprecation |
string |
- | Deprecated indication, if any. |
AcknowledgeRequest
| Name | Type | Format | Description |
|---|---|---|---|
ids |
Array |
string |
The unique identifiers list for the financial documents. |
systemId |
string |
- | The external system ID that acknowledged the documents. |
AcknowledgeResponse
| Name | Type | Format | Description |
|---|---|---|---|
AcknowledgeResponse |
array |
AcknowledgeResponseItem | The JSON response. |
AcknowledgeResponseItem
| Name | Type | Format | Description |
|---|---|---|---|
acknowledgeResult |
string |
- | Acknowledge processing result. Supported values are: SUCCESS or FAILURE. |
code |
Int32 |
Service Codes | The Financial Integration Service Code. This is a particular code based on the success and failure of individual records for Acknowledging documents. |
docId |
string |
- | The financial document unique identifier. Maximum 32 characters. |
errorMessage |
string |
- | The error message, if any. |
systemId |
string |
- | The external system ID that acknowledged the documents. Maximum 50 characters. |
Confirmation Request
| Name | Type | Format | Description |
|---|---|---|---|
systemId |
string |
- | Required The external system ID that acknowledged the documents, it can be an empty string. Maximum 50 characters. |
postingConfirmations |
Array |
Posting Confirmation request item | Posting confirmations JSON request. |
Posting Confirmation Request Item
| Name | Type | Format | Description |
|---|---|---|---|
docId |
string |
- | Required The financial document ID to confirm. Maximum 32 characters. |
overallPostingStatusCode |
string |
- | Required Posting status. VALUES: error or success. |
postingDocs |
array |
Posting Documents Details | Posting documents details, if any. |
systemMessages |
array |
System Messages | Required Messages to post to SAP Concur, if any. |
Posting Documents Details
| Name | Type | Format | Description |
|---|---|---|---|
companyId |
string |
- | Required External system organizational unit ID. Maximum 32 characters. |
documentNumber |
string |
- | External system document identifier. Maximum 80 characters. |
fiscalYear |
int32 |
- | External system fiscal year. |
paymentRelevantLineItems |
array |
- | Payment relevant line items. This array is usually empty. |
postingDate |
string |
YYYY-MM-DD |
External system posting date. |
System Messages
| Name | Type | Format | Description |
|---|---|---|---|
concurTransactionLineItemId |
string |
- | Report relevant line item id. |
messageId |
string |
- | External System message identifier. |
messageLanguage |
string |
- | Message Language code, example EN, FR. |
messageLongText |
array |
- | Message text, will be posted on the audit trail in SAP Concur. Maximum 1300 characters. |
messageShortText |
string |
- | Message text, will be posted on the audit trail in SAP Concur. Maximum 1300 characters. |
Posting Confirmation Response
| Name | Type | Format | Description |
|---|---|---|---|
PostingConfirmationResponse |
array |
Posting Confirmation Response Item | The JSON response body. |
PostingConfirmationResponseItem
| Name | Type | Format | Description |
|---|---|---|---|
postingConfirmationResult |
string |
- | Posting confirmation result. Supported values: SUCCESS, SYSTEM_ERROR_OCCURRED, NOT_YET_ACKNOWLEDGED, DOCUMENT_NOT_FOUND, FAILURE, WAS_RECALLED |
detailMessage |
string |
- | Posting confirmation message. |
code |
Int32 |
- | The Financial Service return code. |
docId |
string |
- | The document ID. Maximum 32 characters. |
errorMessage |
string |
- | The error message, if any. |
systemId |
string |
- | The external system ID that acknowledged the document. Maximum 50 characters. |
Payment Confirmation Request
| Name | Type | Format | Description |
|---|---|---|---|
systemId |
string |
- | Required The external system ID that acknowledged the documents, it can be an empty string. Maximum 50 characters. |
processingConfirmation |
Array |
Payment Confirmation Request Item | Payment confirmations JSON request. |
Payment Confirmation Request Item
| Name | Type | Format | Description |
|---|---|---|---|
docId |
string |
- | The financial document ID to confirm. Maximum 32 characters. |
processingStatusCode |
string |
- | Payment status. Supported values: CP, PP, RE, OB (Completely Paid, Partially paid, Reversal, Obsolete). Maximum 3 characters. |
additionalMessage |
string |
- | Reversal message or obsolete message, if any. |
clearingDetails |
array |
Payment Documents Details | Payment documents details, if any. |
Payment Documents Details
| Name | Type | Format | Description |
|---|---|---|---|
clearingDate |
string |
- | Date the payment cleared. |
clearingAmount |
double |
- | Amount cleared. |
clearingCurrency |
string |
- | Currency value. |
receiver |
array |
Receiver Details | Receiver details. |
clearingReference |
array |
Clearing Reference Details | Clearing reference details. |
Receiver Details
| Name | Type | Format | Description |
|---|---|---|---|
receiverId |
string |
- | Receiver ID. |
receiverName |
double |
- | Name of receiver. |
receiverType |
string |
- | Type of receiver. |
Clearing Reference Details
| Name | Type | Format | Description |
|---|---|---|---|
companyCode |
string |
- | Company code. |
financialDocumentId |
string |
- | Document ID in ERP. |
fiscalYear |
string |
- | Fiscal year. |
paymentRef |
string |
- | Payment reference ID. |
paymentMethod |
string |
- | Payment method Where E = Electronic Fund Transfer or C = Check. |
Payment Confirmation Response
| Name | Type | Format | Description |
|---|---|---|---|
PaymentConfirmationResponse |
array |
Payment Confirmation Response Item | The JSON response body |
PaymentConfirmationResponseItem
| Name | Type | Format | Description |
|---|---|---|---|
paymentConfirmationResult |
string |
- | Payment confirmation result. Supported values: SUCCESS, SYSTEM_ERROR_OCCURRED, NOT_POSTING_CONFIRMED, DOCUMENT_NOT_FOUND, FAILURE, NOOP |
paymentRef |
string |
- | Any message corresponding to payment reference being processed. |
detailMessage |
string |
- | Payment confirmation message. |
code |
Int32 |
- | The financial service return code. |
docId |
string |
- | The document ID. Maximum 32 characters. |
errorMessage |
string |
- | The error message, if any. |
systemId |
string |
- | The external system ID that acknowledged the document. Maximum 50 characters. |
Example Financial Documents
Expense
{
"employee": {
"employeeFirstName": "FirstName",
"employeeLastName": "LastName",
"employeeId": "12345AB",
"employeeMI": null,
"employeeOrgUnit4Value": null,
"employeeOrgUnit5Value": null,
"employeeOrgUnit6Value": null,
"employeeCustom1Code": null,
"employeeCustom2Code": null,
"employeeCustom3Code": null,
"employeeCustom4Code": "001",
"employeeCustom5Code": "USPUG",
"employeeCustom6Code": "1234",
"employeeCustom7Code": null,
"employeeCustom8Code": null,
"employeeCustom9Code": null,
"employeeCustom10Code": null,
"employeeCustom11Code": null,
"employeeCustom12Code": null,
"employeeCustom13Code": null,
"employeeCustom14Code": null,
"employeeCustom15Code": null,
"employeeCustom16Code": "N",
"employeeCustom17Code": null,
"employeeCustom18Code": null,
"employeeCustom19Code": null,
"employeeCustom20Code": null,
"employeeCustom21Code": "US Group",
"employeeCustom1Value": null,
"employeeCustom2Value": null,
"employeeCustom3Value": null,
"employeeCustom4Value": "US Inc.",
"employeeCustom5Value": "US Publishing",
"employeeCustom6Value": "Operations",
"employeeCustom7Value": null,
"employeeCustom8Value": null,
"employeeCustom9Value": null,
"employeeCustom10Value": null,
"employeeCustom11Value": null,
"employeeCustom12Value": null,
"employeeCustom13Value": null,
"employeeCustom14Value": null,
"employeeCustom15Value": null,
"employeeCustom16Value": null,
"employeeCustom17Value": null,
"employeeCustom18Value": null,
"employeeCustom19Value": null,
"employeeCustom20Value": null,
"employeeCustom21Value": "US Group",
"employeeOrgUnit1Code": null,
"employeeOrgUnit2Code": null,
"employeeOrgUnit3Code": null,
"employeeOrgUnit4Code": null,
"employeeOrgUnit5Code": null,
"employeeOrgUnit6Code": null,
"employeeOrgUnit1Value": null,
"employeeOrgUnit2Value": null,
"employeeOrgUnit3Value": null
},
"report": {
"reportKey": 345,
"ledgerCode": "DEFAULT",
"reportId": "D0719B539ED64FE612AB",
"totalApprovedAmount": 200,
"reportName": "Trip to Minneapolis",
"isTest": "N",
"reportStartDate": null,
"reportEndDate": null,
"employeeCurrencyAlphaCode": "USD",
"payrollPayIndicator": "N",
"payrollPaymentClearingAccountCode": null,
"cashAdvanceReturnsAmount": 0E-8,
"revisionNumber": "1",
"versionId": "4",
"homeCountryCode": "US",
"reportCustom20Code": null,
"reportCustom1Value": null,
"reportCustom2Value": null,
"reportCustom3Value": null,
"reportCustom4Value": null,
"reportCustom5Value": null,
"reportCustom6Value": null,
"reportCustom7Value": null,
"reportCustom8Value": null,
"reportCustom9Value": null,
"reportCustom10Value": null,
"reportCustom11Value": null,
"reportCustom12Value": null,
"reportCustom13Value": null,
"reportCustom14Value": null,
"reportCustom15Value": "US Group",
"reportCustom16Value": null,
"reportCustom17Value": null,
"reportCustom18Value": null,
"reportCustom19Value": null,
"reportCustom20Value": null,
"reportOrgUnit1Code": null,
"reportOrgUnit2Code": null,
"reportOrgUnit3Code": null,
"reportOrgUnit4Code": null,
"reportOrgUnit5Code": null,
"reportOrgUnit6Code": null,
"reportOrgUnit1Value": null,
"reportOrgUnit2Value": null,
"reportCustom5Code": null,
"reportCustom6Code": null,
"reportCustom7Code": null,
"reportCustom8Code": null,
"reportCustom9Code": null,
"reportCustom10Code": null,
"reportCustom11Code": null,
"reportCustom12Code": null,
"reportCustom13Code": null,
"reportCustom14Code": null,
"reportCustom15Code": "US Group",
"reportCustom16Code": "12345AB",
"reportCustom17Code": null,
"reportCustom18Code": null,
"reportCustom19Code": null,
"reportSubmitDate": "2018-03-02T18:12:03.050Z",
"reportUserDefinedDate": "2018-03-02T00:00:00.000Z",
"reportPaymentProcessingDate": "2018-03-02T18:34:30.260Z",
"reportCreationDate": "2018-03-02T18:08:37.887Z",
"reportCustom1Code": "12345AB",
"reportCustom2Code": null,
"reportCustom3Code": null,
"reportCustom4Code": null,
"reportOrgUnit3Value": null,
"reportOrgUnit4Value": null,
"reportOrgUnit5Value": null,
"reportOrgUnit6Value": null
},
"expenseEntry": [
{
"cardProgramTypeCode": null,
"entryCustom20Code": null,
"entryCustom21Code": null,
"entryCustom22Code": null,
"entryCustom23Code": null,
"entryCustom24Code": null,
"entryCustom25Code": null,
"entryCustom26Code": null,
"entryCustom27Code": null,
"entryCustom28Code": null,
"entryCustom29Code": null,
"entryCustom30Code": null,
"entryCustom31Code": null,
"entryCustom32Code": null,
"entryCustom33Code": null,
"entryCustom34Code": null,
"entryCustom35Code": "US",
"entryCustom36Code": null,
"entryCustom37Code": null,
"entryCustom38Code": null,
"entryCustom39Code": "0.00000000",
"entryCustom40Code": "200.00000000",
"reportEntryTransactionAmount": 200,
"entryLocationCityName": "Minneapolis",
"entryCountrySubCode": "US-MN",
"entryIsBillable": "N",
"entryOrgUnit1Code": null,
"entryOrgUnit2Code": null,
"entryOrgUnit3Code": null,
"entryOrgUnit4Code": null,
"entryOrgUnit5Code": null,
"entryOrgUnit6Code": null,
"offsetPayType": "N",
"entryCountryCode": "US",
"entryUuid": null,
"entrySupplierTaxID": null,
"entryCustom1Code": null,
"entryCustom2Code": null,
"entryCustom3Code": null,
"entryCustom4Code": null,
"entryCustom5Code": null,
"entryCustom6Code": null,
"entryCustom7Code": null,
"entryCustom8Code": null,
"entryCustom9Code": null,
"entryCustom10Code": null,
"entryCustom11Code": null,
"entryCustom12Code": null,
"entryCustom13Code": null,
"entryCustom14Code": null,
"entryCustom15Code": null,
"entryCustom16Code": null,
"entryCustom17Code": null,
"entryCustom18Code": null,
"entryCustom19Code": null,
"cardAccountID": null,
"cardTransactionID": null,
"cardTransactionAmount": null,
"cardTransactionCurrency": null,
"cardTransactionPostedAmount": null,
"cardTransactionPostedCurrency": null,
"clearingAccountCode": null,
"entryApprovedAmount": 200,
"expensePayIndicator": "N",
"entryId": "A92F3AD820F4E546800515258C3E0893",
"entryDescription": "",
"entryVendorCode": "Astron Hotels",
"entryCustom1Value": null,
"entryCustom2Value": null,
"entryCustom3Value": null,
"entryCustom4Value": null,
"entryCustom5Value": null,
"entryCustom6Value": null,
"entryCustom7Value": null,
"entryCustom8Value": null,
"entryCustom9Value": null,
"entryCustom10Value": null,
"entryCustom11Value": null,
"entryCustom12Value": null,
"entryCustom13Value": null,
"entryCustom14Value": null,
"entryCustom15Value": null,
"entryCustom16Value": null,
"entryCustom17Value": null,
"entryCustom18Value": null,
"entryCustom19Value": null,
"entryCustom20Value": null,
"entryCustom21Value": null,
"entryCustom22Value": null,
"entryCustom23Value": null,
"entryCustom24Value": null,
"entryCustom25Value": null,
"entryCustom26Value": null,
"entryCustom27Value": null,
"entryCustom28Value": null,
"entryCustom29Value": null,
"entryCustom30Value": null,
"entryCustom31Value": null,
"entryCustom32Value": null,
"entryCustom33Value": null,
"entryCustom34Value": null,
"entryCustom35Value": null,
"entryCustom36Value": null,
"entryCustom37Value": null,
"entryCustom38Value": null,
"entryCustom39Value": null,
"entryCustom40Value": null,
"entryOrgUnit1Value": null,
"entryOrgUnit2Value": null,
"entryOrgUnit3Value": null,
"entryOrgUnit4Value": null,
"entryOrgUnit5Value": null,
"entryOrgUnit6Value": null,
"entryLocationName": "Minneapolis",
"entryReceiptId": "E921EECCBCBA393EAC5A9212DCE57D9B",
"entryElectronicReceiptId": null,
"allocation": [
{
"allocationId": "76A1774FEC7D0C4981FBB332AB5671A3",
"allocationCustom1Code": "",
"allocationCustom2Code": "",
"allocationCustom3Code": "",
"allocationCustom4Code": null,
"allocationCustom5Code": null,
"allocationCustom6Code": null,
"allocationCustom7Code": null,
"allocationCustom8Code": null,
"allocationCustom9Code": null,
"allocationCustom10Code": null,
"allocationCustom11Code": null,
"allocationCustom12Code": null,
"allocationCustom13Code": null,
"allocationCustom14Code": null,
"allocationCustom15Code": null,
"allocationCustom16Code": null,
"allocationCustom17Code": null,
"allocationCustom18Code": null,
"allocationCustom19Code": null,
"allocationCustom20Code": null,
"allocationCustom1Value": null,
"allocationCustom2Value": null,
"allocationCustom3Value": null,
"allocationCustom4Value": null,
"allocationCustom5Value": null,
"allocationCustom6Value": null,
"allocationCustom7Value": null,
"allocationCustom8Value": null,
"allocationCustom9Value": null,
"allocationCustom10Value": null,
"allocationCustom11Value": null,
"allocationCustom12Value": null,
"allocationCustom13Value": null,
"allocationCustom14Value": null,
"allocationCustom15Value": null,
"allocationCustom16Value": null,
"allocationCustom17Value": null,
"allocationCustom18Value": null,
"allocationCustom19Value": null,
"allocationCustom20Value": null,
"allocationPercentage": 100,
"journal": [
{
"amountGrossCard": null,
"journalAccountCode": "125ABC",
"journalPayee": "EMPL",
"journalPayer": "COMP",
"cardTransactionReferenceNumber": null,
"amountNetOfReclaim": 150,
"amountNetOfTax": 150,
"amountGross": 150,
"taxGuid": [],
"accountingTransactionType": null
},
{
"amountGrossCard": null,
"journalAccountCode": "12345",
"journalPayee": "EMPL",
"journalPayer": "COMP",
"cardTransactionReferenceNumber": null,
"amountNetOfReclaim": 50,
"amountNetOfTax": 50,
"amountGross": 50,
"taxGuid": [],
"accountingTransactionType": null
}
],
"tax": []
}
],
"entryReceiptType": "N",
"entryExchangeRateDirection": "M",
"entryIsPersonal": "N",
"entryVendorDescription": "Astron Hotels",
"legacyEntryId": 294,
"liabilityAccountCode": null,
"expenseTypeName": "Hotel",
"entryDate": "2018-02-17T00:00:00.000Z",
"entryCurrAlphaCode": "USD",
"entryExchangeRate": 1,
"expenseTypeCode": "LODNG",
"cardStatementPeriodStartDate": null,
"cardStatementPeriodEndDate": null,
"reportEntryPatKey": "CASH"
}
],
"cashAdvanceApplication": [
{
"cashAdvanceClearingAccountCode": "12345",
"cashAdvanceId": "6A107A548D1B4B49BBF370DF02EC890D",
"cashAdvanceApplicationAmount": -50,
"cashAdvanceTransactionType": 2
}
]
}
Invoice
{
"requestHeader":{
"ledgerCode":"DEFAULT",
"clearingAccountCode":null,
"invoiceDate":"08/08/2018",
"reqKey":35,
"postingDate":null,
"poNumber":null,
"isTest":"N",
"deliverySlipNumber":null,
"discountPercentage":null,
"paymentDueDate":"09/07/2018",
"requestId":"9B1D30723CBF4F86A574",
"requestOrgUnit4Code":null,
"requestOrgUnit5Code":null,
"requestOrgUnit6Code":null,
"currencyAlphaCode":"USD",
"ledgerName":"DEFAULT",
"vendorInvoiceNumber":"25688",
"multiplePurchaseOrder":"N",
"invoicePayIndicator":"N",
"payMethodType":"CLIENT",
"submitDate":"2018-09-05T03:37:42.923Z",
"requestTotal":50.00000000,
"revisionNumber":"1",
"processCompleteDate":null,
"invoiceReceivedDate":null,
"requestOrgUnit1Value":null,
"requestOrgUnit2Value":null,
"requestOrgUnit3Value":null,
"requestOrgUnit4Value":null,
"requestOrgUnit5Value":null,
"requestOrgUnit6Value":null,
"versionId":"4",
"requestOrgUnit1Code":null,
"requestOrgUnit2Code":null,
"requestOrgUnit3Code":null,
"requestCustom21Code":null,
"requestCustom22Code":null,
"requestCustom1Value":null,
"requestCustom2Value":null,
"requestCustom3Value":null,
"requestCustom4Value":null,
"requestCustom5Value":null,
"requestCustom6Value":null,
"requestCustom7Value":null,
"requestCustom8Value":null,
"requestCustom9Value":null,
"requestCustom10Value":"Default-Change to Client",
"requestCustom11Value":null,
"requestCustom12Value":null,
"requestCustom13Value":null,
"requestCustom14Value":null,
"requestCustom15Value":null,
"requestCustom16Value":null,
"requestCustom17Value":null,
"requestCustom18Value":null,
"requestCustom19Value":null,
"requestCustom20Value":null,
"requestCustom21Value":null,
"requestCustom22Value":null,
"requestCustom23Value":null,
"requestCustom24Value":null,
"amountNetInvoice":50.00000000,
"amountShippingTotal":0E-8,
"requestTitle":"FIS Test",
"discountTermsDays":null,
"requestCustom1Code":null,
"requestCustom2Code":null,
"requestCustom3Code":null,
"requestCustom4Code":null,
"requestCustom5Code":null,
"requestCustom6Code":null,
"requestCustom7Code":null,
"requestCustom8Code":null,
"requestCustom9Code":null,
"requestCustom10Code":"Default",
"requestCustom11Code":null,
"requestCustom12Code":null,
"requestCustom13Code":null,
"requestCustom14Code":null,
"requestCustom15Code":null,
"requestCustom16Code":null,
"requestCustom17Code":null,
"requestCustom18Code":null,
"requestCustom19Code":null,
"requestCustom20Code":null,
"requestCustom24Code":null,
"netPaymentTermDays":"30",
"requestCreationDate":"2018-09-05T03:37:00.143Z",
"requestCustom23Code":null,
"requestDescription":null
},
"ownerEmployee":{
"employeeCustom20Value":null,
"employeeCustom21Value":"System",
"employeeCustom10Code":"Default",
"employeeOrgUnit1Code":null,
"employeeOrgUnit2Code":null,
"employeeOrgUnit3Code":null,
"employeeOrgUnit4Code":null,
"employeeOrgUnit5Code":null,
"employeeOrgUnit6Code":null,
"employeeOrgUnit1Value":null,
"employeeOrgUnit2Value":null,
"employeeOrgUnit3Value":null,
"employeeOrgUnit4Value":null,
"employeeOrgUnit5Value":null,
"employeeOrgUnit6Value":null,
"employeeCustom1Code":"ext-record-4",
"employeeCustom2Code":null,
"employeeCustom3Code":null,
"employeeCustom4Code":null,
"employeeCustom5Code":null,
"employeeCustom6Code":null,
"employeeCustom7Code":null,
"employeeCustom8Code":null,
"employeeCustom9Code":"28",
"employeeCustom11Code":null,
"employeeCustom13Code":null,
"employeeCustom14Code":null,
"employeeCustom15Code":null,
"employeeCustom16Code":"N",
"employeeCustom17Code":null,
"employeeCustom18Code":null,
"employeeCustom19Code":null,
"employeeCustom20Code":null,
"employeeCustom21Code":"SYS",
"employeeCustom1Value":null,
"employeeCustom2Value":null,
"employeeCustom3Value":null,
"employeeCustom4Value":null,
"employeeCustom5Value":null,
"employeeCustom6Value":null,
"employeeCustom7Value":null,
"employeeCustom8Value":null,
"employeeCustom9Value":"522 Product",
"employeeCustom10Value":"Default-Change to Client",
"employeeCustom11Value":null,
"employeeCustom12Value":null,
"employeeCustom13Value":null,
"employeeCustom14Value":null,
"employeeCustom15Value":null,
"employeeCustom16Value":null,
"employeeCustom17Value":null,
"employeeCustom18Value":null,
"employeeCustom19Value":null,
"employeeId":"12345AB",
"employeeMI":"C",
"employeeFirstName":"FirstName",
"employeeLastName":"LastName",
"employeeCustom12Code":null
},
"vendor":{
"vendorName":"Test Vendor",
"vendorCode":"94F538F2C3224C6E871CFED9F0F8333A",
"vendorShipFromAddressCode":null,
"vendorRemitToAddressCode":"333",
"vendorContactFirstName":null,
"vendorContactLastName":null
},
"lineItem":[
{
"allocation":[
{
"journal":{
"accountCode":"MATER",
"amountShipping":0,
"amountNet":50.00,
"amountGross":50.00,
"tax":null
},
"allocationAccountCode":"MATER",
"allocationCustom6Code":null,
"allocationCustom7Code":null,
"allocationCustom8Code":null,
"allocationCustom9Code":null,
"allocationCustom10Code":null,
"allocationCustom11Code":null,
"allocationCustom12Code":null,
"allocationCustom13Code":null,
"allocationCustom14Code":null,
"allocationCustom15Code":null,
"allocationCustom16Code":null,
"allocationCustom17Code":null,
"allocationCustom18Code":null,
"allocationCustom19Code":null,
"allocationCustom20Code":null,
"allocationCustom1Code":"",
"allocationCustom2Code":"",
"allocationCustom3Code":"",
"allocationCustom4Code":null,
"allocationCustom5Code":null,
"allocationPercentage":100.00000000,
"allocationCustom1Value":null,
"allocationCustom2Value":null,
"allocationCustom3Value":null,
"allocationCustom4Value":null,
"allocationCustom5Value":null,
"allocationCustom6Value":null,
"allocationCustom7Value":null,
"allocationCustom8Value":null,
"allocationCustom9Value":null,
"allocationCustom10Value":null,
"allocationCustom11Value":null,
"allocationCustom12Value":null,
"allocationCustom13Value":null,
"allocationCustom14Value":null,
"allocationCustom15Value":null,
"allocationCustom16Value":null,
"allocationCustom17Value":null,
"allocationCustom18Value":null,
"allocationCustom19Value":null,
"allocationCustom20Value":null,
"allocationKey":158
}
],
"receiptNumbers":[
],
"expenseTypeName":"Material",
"poLineNumber":null,
"externalLineItemId":null,
"expenseTypeCode":"2000 ",
"lineItemPurchaseOrderNumber":null,
"lineItemCode":null,
"lineItemDeliverySlipNumber":null,
"lineItemUnitPrice":50.00000000,
"lineItemSequenceOrder":1,
"lineItemQuantity":1.00000000,
"lineItemCustom1Value":null,
"lineItemCustom2Value":null,
"lineItemCustom3Value":null,
"lineItemCustom4Value":null,
"lineItemCustom5Value":null,
"lineItemCustom6Value":null,
"lineItemCustom7Value":null,
"lineItemCustom8Value":null,
"lineItemCustom9Value":null,
"lineItemCustom10Value":null,
"lineItemCustom11Value":null,
"lineItemCustom12Value":null,
"lineItemCustom13Value":null,
"lineItemCustom14Value":null,
"lineItemCustom15Value":null,
"lineItemCustom16Value":null,
"lineItemCustom17Value":null,
"lineItemCustom18Value":null,
"lineItemCustom19Value":null,
"lineItemCustom20Value":null,
"lineItemCustom1Code":null,
"lineItemCustom2Code":null,
"lineItemCustom3Code":null,
"lineItemCustom4Code":null,
"lineItemCustom5Code":null,
"lineItemCustom6Code":null,
"lineItemCustom7Code":null,
"lineItemCustom8Code":null,
"lineItemCustom9Code":null,
"lineItemCustom10Code":null,
"lineItemCustom11Code":null,
"lineItemCustom12Code":null,
"lineItemCustom13Code":null,
"lineItemCustom14Code":null,
"lineItemCustom15Code":null,
"lineItemCustom16Code":null,
"lineItemCustom17Code":null,
"lineItemCustom18Code":null,
"lineItemCustom19Code":null,
"lineItemCustom20Code":null,
"lineItemDescription":"Merchandise"
}
]
}
Cash Advance
{
"employeeData": {
"employeeFirstName": "FirstName",
"employeeLastName": "LastName",
"employeeId": "12345ID",
"employeeMI": null,
"employeeOrgUnit5Code": null,
"employeeOrgUnit6Code": null,
"employeeOrgUnit1Value": null,
"employeeOrgUnit2Value": null,
"employeeOrgUnit3Value": null,
"employeeOrgUnit4Value": null,
"employeeOrgUnit5Value": null,
"employeeOrgUnit6Value": null,
"employeeCustom1Code": null,
"employeeCustom2Code": null,
"employeeCustom3Code": null,
"employeeCustom4Code": "001",
"employeeCustom5Code": "ABUFG",
"employeeCustom6Code": "2567",
"employeeCustom7Code": null,
"employeeCustom8Code": null,
"employeeCustom9Code": null,
"employeeCustom10Code": null,
"employeeCustom11Code": null,
"employeeCustom13Value": null,
"employeeCustom14Value": null,
"employeeCustom15Value": null,
"employeeCustom16Value": null,
"employeeCustom17Value": null,
"employeeCustom18Value": null,
"employeeCustom19Value": null,
"employeeCustom20Value": null,
"employeeCustom21Value": "US Group",
"employeeCustom12Code": null,
"employeeCustom13Code": null,
"employeeCustom14Code": null,
"employeeCustom15Code": null,
"employeeCustom16Code": "N",
"employeeCustom17Code": null,
"employeeCustom18Code": null,
"employeeCustom19Code": null,
"employeeCustom20Code": null,
"employeeCustom21Code": "US Group",
"employeeCustom1Value": null,
"employeeCustom2Value": null,
"employeeCustom3Value": null,
"employeeCustom4Value": "US Inc.",
"employeeCustom5Value": "US Publishing",
"employeeCustom6Value": "Operations",
"employeeCustom7Value": null,
"employeeCustom8Value": null,
"employeeCustom9Value": null,
"employeeCustom10Value": null,
"employeeCustom11Value": null,
"employeeCustom12Value": null,
"employeeOrgUnit1Code": null,
"employeeOrgUnit2Code": null,
"employeeOrgUnit3Code": null,
"employeeOrgUnit4Code": null
},
"cashAdvanceData": {
"locationName": null,
"exchangeRate": 1,
"countryCode": null,
"currencyAlphaCode": "USD",
"cashAdvanceId": "FE884EE31617CF4CABE36C7FC44512A1",
"clearingAccountCode": null,
"purpose": null,
"paymentMethod": 0,
"requestAmount": 150,
"requestDate": "2018-03-03T02:16:51.363Z",
"issuedDate": "2018-03-06T03:54:36.993Z",
"isTest": "N",
"countrySubCode": null,
"requestedDisbursementDate": null,
"travelStartDate": null,
"travelEndDate": null,
"currencyNumCode": "840",
"expensePayIndicator": "N",
"employeeCurrencyAlphaCode": "USD",
"cardAccountID": null,
"cardTransactionID": null,
"cardTransactionAmount": null,
"cardTransactionCurrency": null,
"cardTransactionPostedAmount": null,
"cardTransactionPostedCurrency": null,
"transactionType": 1,
"name": "Cash Advance Testing 3"
},
"journalData": [
{
"accountCode": "12345",
"amount": 150,
"payee": "EMPL",
"debitOrCredit": "DR",
"payer": "COMP",
"paymentCode": "Cash"
}
]
}
IMAGE
Receipt Image v3
- Scope Usage
- Retrieve a list of all receipt images
- Retrieve a receipt image by ID
- Create a new receipt image
- Append a receipt image
- Delete a receipt image
- Schema
The SAP Concur Receipt Image API allows for the management of receipt images attached to expense reports, expense entries, and payment requests. You can retrieve existing images by Image ID, and upload new images to a User. This API allows you to upload images in a predefined format and size targeting a specific resource or user in SAP Concur. You can also pull images down from SAP Concur by either displaying them in the browser or downloading the image content to save locally.
Note: This API is not designed to obtain the receipt images attached to an expense report. If you are an Enterprise Partner creating integrations that are intended to obtain final-approved Expense or Invoice data, and the accompanying receipt images that substantiate those transactions you will need to use Image v1. These scenarios include, but are not limited to: ERP integrations for financial journal entry postings, VAT reclaim integrations that obtain transactions to calculate VAT reclaim, project billing integrations used to substantiate expenses billed back, etc.
Scope Usage
| Name | Description | Endpoint |
|---|---|---|
IMAGE |
Add or Retrieve Report and Line Item Images. | GET, POST, PUT, DELETE |
Retrieve a List of All Receipt Images
GET /api/v3.0/expense/receiptimages
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
offset |
string |
query |
Starting page offset |
limit |
Int32 |
query |
Number of records to return (default 25) |
user |
string |
query |
The login ID of the user. Optional. The user must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter. |
Retrieve a Receipt Image by ID
GET /api/v3.0/expense/receiptimages/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required ReceiptImage ID |
user |
string |
query |
The login ID of the user. Optional. The user must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter. |
Example
The above GET request produces this response:
<Image xmlns="http://www.concursolutions.com/api/image/2011/02" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Id>sample</Id>
<Url>https://imagingupload.concursolutions.com/file/p00884704c6o/5A789811F139BC89D9C42DDE5FEE2A655BB7C2A375E9C481FA0BE92FFF690E298F119925A5C834385C8D62AE5FC4E65AC0F53E4C7273C14A4E71D4264F104882H142570AF84FBEEEC439486FE89E44D2F?id=51253775812C4750888F2e=p00884704c6o3t=AN</Url>
</Image>
Copy and paste the URL into a browser session to render the image. This is a temporary URL.
Create a New Receipt Image
POST /api/v3.0/expense/receiptimages
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
user |
string |
query |
The login ID of the user. Optional. The user must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter. |
image |
file |
body |
Required Image data file |
Append a Receipt Image
PUT /api/v3.0/expense/receiptimages/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required ID of the receipt image to update |
user |
string |
query |
The login ID of the user. Optional. The user must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter. |
image |
file |
body |
Required Image data file |
Delete a Receipt Image
DELETE /api/v3.0/expense/receiptimages/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required ID of the receipt image to delete |
user |
string |
query |
The login ID of the user. Optional. The user must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter. |
Schema
Receipt Images
| Name | Type | Format | Description |
|---|---|---|---|
Items |
Array | Receipt Image | The result collection. |
NextPage |
string | - | The URI of the next page of results, if any. |
Receipt Image
| Name | Type | Format | Description |
|---|---|---|---|
ID |
string | - | The unique identifier of the resource. |
URI |
string | - | The URI to the resource. |
INSIGHTS
Latest Bookings
Gets the latest hotel and air booking for a particular user.
Version
3.0
Retrieve the latest hotel and air booking for a particular user
GET /api/v3.0/insights/latestbookings/
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
user |
string |
query |
The login ID of the user. The user must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter. |
Schema
Latest Booking
| Name | Type | Format | Description |
|---|---|---|---|
Airlines |
array |
Airline | The latest booked airline segments. |
Hotel |
Hotel |
- | The latest booked hotel segment. |
Airline
| Name | Type | Format | Description |
|---|---|---|---|
BookingClass |
string |
- | The booking class of the latest booked airline segment. |
Code |
string |
- | The airline code of the latest booked airline segment. |
Hotel
| Name | Type | Format | Description |
|---|---|---|---|
Location |
string |
- | The IATA airport code of the location of the latest booked hotel segment. |
StarRating |
Int32 |
- | The star rating of the latest booked hotel segment. Possible values are from 0 - 5. Values 1 - 5 are mapped to the Northstar standard. If the value is 0, the star rating could not be found. |
Opportunities
Retrieves a collection of opportunities for a specified trip or for all trips that fall within a date range.
- Retrieve a collection of opportunities for a specified trip or for all trips that fall within a date range
- Schema
Version
3.0
Retrieve all connection requests that match the TripLink supplier ID
GET https://www.concursolutions.com/api/v3.0/insights/opportunities
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
tripId |
string |
query |
The trip id |
opportunityType |
string |
query |
Comma seperated list of opportunities (Hotel, Car, Air, Rail, Taxi and Service) to get. Do not specify any values to get all opportunities |
fromUtc |
DateTime |
query |
The From date in UTC for the date range |
toUtc |
DateTime |
query |
The To date in UTC for the date range |
Schema
Opportunities
| Name | Type | Format | Description |
|---|---|---|---|
Items |
Array |
Opportunity | The result collection. |
NextPage |
string |
- | The URI of the next page of results, if any. |
Opportunity
| Name | Type | Format | Description |
|---|---|---|---|
EndCityCode |
string |
- | The city code of the destination city where the opportunity is offered |
EndDateLocal |
DateTime |
- | The local end date of the location where the opportunity is offered |
EndPostalCode |
string |
- | The postal code of the destination location where the opportunity is offered |
ID |
string |
- | The unique identifier of the resource. |
IsActive |
boolean |
- | Indicates that the opportunity is currently active |
StartCityCode |
string |
- | The city code of the originating city where the opportunity is offered |
StartDateLocal |
DateTime |
- | The local start date of the location where the opportunity is offered |
StartPostalCode |
string |
- | The postal code of the originating location where the opportunity is offered |
TripId |
string |
- | The trip id of the associated itinerary |
Type |
string |
- | The type of opportunity. Possible values: 'Hotel', 'Car', 'Air', 'Rail', 'Taxi' or 'Service' |
URI |
string |
- | The URI to the resource. |
INVOICE
Retrieve Invoice Digests v3
- Retrieves All Invoice Digests Based On the Search Criteria
- Retrieves an Invoice Digest Based On ID
- Schema
Version
3.0
Retrieves All Invoice Digests Based On the Search Criteria
GET /api/v3.0/invoice/paymentrequestdigests
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
offset |
string |
query |
The start of the page offset. |
limit |
Int32 |
query |
The number of records to return. Default: 1,000 |
approvalStatus |
string |
query |
A code representing an Invoice Approval Status. Use GET /invoice/localizeddata to get the available approval status codes. |
paymentStatus |
string |
query |
A code representing an Invoice Payment Status. Use GET /invoice/localizeddata to get the available payment status codes |
vendorInvoiceNumber |
string |
query |
Vendor invoice number tied to the invoice. |
createDateBefore |
DateTime |
YYYY-MM-DD |
The invoice create date is before this date. |
createDateAfter |
DateTime |
YYYY-MM-DD |
The invoice create date is after this date. |
userDefinedDateBefore |
DateTime |
YYYY-MM-DD |
The invoice user defined date is before this date. |
userDefinedDateAfter |
DateTime |
YYYY-MM-DD |
The invoice user defined date is after this date. |
submitDateBefore |
DateTime |
YYYY-MM-DD |
The invoice submit date is before this date. |
submitDateAfter |
DateTime |
YYYY-MM-DD |
The invoice submit date is after this date. |
paidDateBefore |
DateTime |
YYYY-MM-DD |
The invoice paid date is before this date. |
paidDateAfter |
DateTime |
YYYY-MM-DD |
The invoice paid date is after this date. |
payMethodType |
string |
query |
Payment method type tied to an Invoice. Use GET /invoice/localizeddata to get the available Pay Method types. |
lastModifiedDateBefore |
DateTime |
YYYY-MM-DD |
The invoice last modified date is before this date. |
lastModifiedDateAfter |
DateTime |
YYYY-MM-DD |
The invoice last modified date is after this date. |
extractedDateBefore |
DateTime |
YYYY-MM-DD |
The invoice extracted date is before this date. |
extractedDateAfter |
DateTime |
YYYY-MM-DD |
The invoice extracted date is after this date. |
Retrieves an Invoice Digest Based On ID
GET /api/v3.0/invoice/paymentrequestdigests/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required The invoice ID |
Schema
Payment Request Digests
| Name | Type | Format | Description |
|---|---|---|---|
Items |
Array |
Payment Request Digest | The result collection. |
NextPage |
string |
- | The URI of the next page of results, if any. |
PaymentRequestDigest |
Array |
Payment Request Digest | - |
TotalCount |
Int32 |
- | - |
Payment Request Digest
| Name | Type | Format | Description |
|---|---|---|---|
ApprovalStatusCode |
string |
- | Required A code indicating the invoice's approval status. |
CreateDate |
string |
- | The date the invoice was created. |
CurrencyCode |
string |
- | The 3-letter ISO 4217 currency code for the invoice currency. Examples: USD - US dollars; BRL - Brazilian real; CAD - Canadian dollar; CHF - Swiss franc; EUR - Euro; GBO - Pound sterling; HKD - Hong Kong dollar; INR - Indian rupee; MXN - Mexican peso; NOK - Norwegian krone; SEK - Swedish krona. |
ID |
string |
- | The unique identifier of the resource. |
InvoiceNumber |
string |
- | The invoice number of the Invoice. |
IsDeleted |
boolean |
- | A true/false value which indicates whether the invoice has been deleted. (Deleted invoices are retained in the system for historical purposes.). |
OwnerLoginID |
string |
- | The login ID of the Invoice owner. |
OwnerName |
string |
- | The name of the Invoice owner. |
PaidDate |
string |
- | The date when all journal entries in the invoice were integrated with or extracted to the financial system. |
PaymentRequestId |
string |
- | Required The unique identifier of the Invoice summarized in this digest. |
PaymentRequestUri |
string |
- | Required URI of the Invoice summarized in this digest. |
PaymentStatusCode |
string |
- | Required A code indicating the invoice's payment status. |
Total |
string |
- | The total amount of the invoice. |
URI |
string |
- | The URI to the resource. |
UserDefinedDate |
string |
- | The invoice date as assigned by the user. |
VendorName |
string |
- | Required The name of the vendor. |
PaymentMethod |
string |
- | Payment method type tied to an Invoice. |
LastModifiedDate |
string |
- | The date the invoice was last modified. |
ExtractedDate |
string |
- | The date the invoice was extracted. |
Invoice v3
Version
3.0
Retrieve an Invoice
GET /api/v3.0/invoice/paymentrequest/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
| id | string |
path | Required Invoice ID. |
Create a New Invoice
POST /api/v3.0/invoice/paymentrequest
Payload
Update an Invoice
PUT /api/v3.0/invoice/paymentrequest
Payload
Schema
Payment Request
| Name | Type | Format | Description |
|---|---|---|---|
AmountWithoutVat |
string |
- | The net amount of the invoice (excluding VAT). |
BuyerCostCenter |
string |
- | The company defined center responsible for the Invoice. |
CheckNumber |
string |
- | Check number of the payment made to the vendor. |
CompanyBillToAddressCode |
string |
- | The code which identifies the company location to which the vendor billed the invoice. |
CompanyShipToAddressCode |
string |
- | The code which identifies the company location to which the vendor shipped items listed in the invoice. |
CountryCode |
string |
- | Required The country code. |
CurrencyCode |
string |
- | The 3-letter ISO 4217 currency code for the invoice currency. Examples: USD - US dollars; BRL - Brazilian real; CAD - Canadian dollar; CHF - Swiss franc; EUR - Euro; GBO - Pound sterling; HKD - Hong Kong dollar; INR - Indian rupee; MXN - Mexican peso; NOK - Norwegian krone; SEK - Swedish krona. |
Custom1 through Custom24 |
string |
- | The details from the Custom fields. These may not have data, depending on configuration. |
DataSource |
string |
- | A code which indicates the method used to created the Invoice. Use GET /invoice/localizeddata to translate the code into text. |
DeliverySlipNumber |
string |
- | The delivery slip number associated with receiving receipt. |
Description |
string |
- | User entered description of the Invoice. |
DiscountPercentage |
string |
- | The discount from the supplier if the discount terms are met. |
DiscountTerms |
string |
- | The NET discount terms with a supplier when discounts apply. |
EmployeeEmailAddress |
string |
- | The email address of the employee to whom the invoice should be assigned. Not evaluated if EmployeeLoginId or EmployeeId match an employee. This value is required if none of the following are provided: LedgerCode; EmployeeLoginId, EmployeeId; PurchaseOrderNumber; ExternalPolicyId. |
EmployeeId |
string |
- | The company ID of the employee to whom the invoice should be assigned. Has precedence over EmployeeEmail; not evaluated if EmployeeLoginId matches an employee. This value is required if none of the following are provided: LedgerCode; EmployeeLoginId; EmployeeEmail; PurchaseOrderNumber; ExternalPolicyId. |
EmployeeLoginId |
string |
- | The login ID of the employee to whom the invoice should be assigned. Has precedence over EmployeeId and EmployeeEmail. This value is required if none of the following are provided: LedgerCode; EmployeeId; EmployeeEmail; PurchaseOrderNumber; ExternalPolicyId. |
ExternalPolicyId |
string |
- | The external policy ID of the Invoice. This value is required if none of the following are provided: LedgerCode; EmployeeLoginId, EmployeeId; EmployeeEmail; PurchaseOrderNumber. |
InvoiceAmount |
string |
- | Required User-entered value representing the total invoice amount, used to calculate amount remaining on the line item page. |
InvoiceDate |
string |
- | The date the vendor issued the Invoice. |
InvoiceNumber |
string |
- | The Invoice Number from the vendor for the Invoice. |
InvoiceReceivedDate |
string |
- | The date on which the invoice was received. |
IsEmergencyCheckRun |
string |
- | Is an emergency check run required (Y/N). |
IsInvoiceConfirmed |
boolean |
- | Indicates if the Invoice is confirmed or in a different status Supported values: true, false |
LedgerCode |
string |
- | A code which indicates which company journal the Invoice is assigned to. Use GET /invoice/localizeddata to obtain valid codes. This value is required if none of the following are provided: EmployeeLoginId; EmployeeId; EmployeeEmail; PurchaseOrderNumber; ExternalPolicyId. |
LineItems |
array |
LineItem |
The details of the Core Payment Request Line Item Identity Fields. |
Name |
string |
- | Required The Invoice name. |
NotesToVendor |
string |
- | Information from the customer to the vendor for special requests or handling for the ordered good or service. |
OB10BuyerId |
string |
- | A unique buyer account on the OB10 network. |
OB10TransactionId |
string |
- | Unique Identifier for the Invoice transaction (generated by OB10). |
OrgUnit1 |
string |
- | The details from the Organization Unit fields. These may not have data, depending on configuration. |
OrgUnit2 |
string |
- | The details from the Organization Unit fields. These may not have data, depending on configuration. |
OrgUnit3 |
string |
- | The details from the Organization Unit fields. These may not have data, depending on configuration. |
OrgUnit4 |
string |
- | The details from the Organization Unit fields. These may not have data, depending on configuration. |
OrgUnit5 |
string |
- | The details from the Organization Unit fields. These may not have data, depending on configuration. |
OrgUnit6 |
string |
- | The details from the Organization Unit fields. These may not have data, depending on configuration. |
PaymentAdjustmentNotes |
string |
- | Notes to the vendor regarding the amount paid (underpayment due to damages, for example). |
PaymentAmount |
string |
- | Represents the amount of the payment that will be/has been made for the Invoice. |
PaymentDueDate |
string |
- | The date the vendor needs to be paid by. |
PaymentTermsDays |
string |
- | This number, along with type of payment terms (example: NET), determine when the invoice is expected to be paid. |
ProvincialTaxId |
string |
- | The Vendor Provincial Tax ID. |
PurchaseOrderNumber |
string |
- | The ID of the Purchase Order to which the Invoice should be matched. This value is required if none of the following are provided: LedgerCode; EmployeeLoginId, EmployeeId, EmployeeEmail, ExternalPolicyId. |
ReceiptConfirmationType |
string |
- | A code which indicates the receipt confirmation type for this Invoice (Invoice Confirmation, for example). Use GET /invoice/localizeddata to translate the code into text. |
ShippingAmount |
string |
- | The value for the Shipping Amount header field. |
TaxAmount |
string |
- | The value for the Tax Amount header field. |
VatAmountOne |
string |
- | The amount of VAT included in the invoice total (first of two VAT amount fields available). |
VatAmountTwo |
string |
- | The amount of VAT included in the invoice total (second of two VAT amount fields available). |
VatRateOne |
string |
- | The VAT rate applied to the net invoice total (should relate to the first VAT amount field). |
VatRateTwo |
string |
- | The VAT rate applied to the net invoice total (should relate to the second VAT amount field). |
VendorRemitToIdentifier |
object |
VendorRemitToIdentifier |
Required Used to identify the vendor location for payment remittance. At a minimum, the VendorCode or the combination of (VendorName, Address1, and PostalCode) are required. Use of as many fields as possible is encouraged to ensure a single vendor can be identified. If more than one vendor matches the information provided, the Invoice creation attempt will fail. |
VendorShipFromAddressCode |
string |
- | The code which identifies the location from which the vendor shipped items listed in the invoice. |
VendorTaxId |
string |
- | The Vendor Tax ID. |
LineItem
| Name | Type | Format | Description |
|---|---|---|---|
Allocations |
array |
Allocation |
The details of the Invoice allocation fields. |
AmountWithoutVat |
string |
- | The net amount of the line item (excluding VAT). |
Custom1 through Custom20 |
string |
- | The details from the Custom fields. These may not have data, depending on configuration. |
Description |
string |
- | Brief overview of the good or service ordered. |
ExpenseTypeCode |
string |
- | A code which indicates the Expense Type for the Line Item. |
ItemCode |
string |
- | Represents the item code (the unique code a vendor assigns to a good or code a vendor assigns to a good or service to identify it). |
MatchedPurchaseOrderReceipts |
array |
MatchedPurchaseOrderReceipt |
The details of the Matched Purchase Order Receipts Identity Fields (if any). |
PurchaseOrderNumber |
string |
- | Purchase Order that is associated to the Line Item . |
Quantity |
string |
- | Total number of goods or services ordered. |
ShipFromPostalCode |
string |
- | The postal code the good or service was shipped from. |
ShipToPostalCode |
string |
- | The postal code the good or service will be shipped to. |
SupplierPartId |
string |
- | The unique identifier provided by the supplier that is associated with the good or service. |
Tax |
string |
- | The tax associated with the line item. |
TotalPrice |
string |
- | The total amount of the line item. |
UnitOfMeasure |
string |
- | The code for the measurement unit used to quantify the good or service. Use GET /invoice/localizeddata to look up codes and descriptions. |
UnitPrice |
string |
- | The cost for a single unit of the line item good or service. |
VatAmount |
string |
- | The amount of VAT included in the line item total. |
VatRate |
string |
- | The VAT rate applied to the net line item total. |
Allocation
| Name | Type | Format | Description |
|---|---|---|---|
Custom1 through Custom7 |
string |
- | The details from the Custom fields. These may not have data, depending on configuration. |
Custom8 |
string |
- | A value that can be applied to a custom field 8 that is part of the allocation form. |
Custom9 |
string |
- | A value that can be applied to a custom field 9 that is part of the allocation form. |
Custom10 |
string |
- | A value that can be applied to a custom field 10 that is part of the allocation form. |
Custom11 through Custom20 |
string |
- | The details from the Custom fields. These may not have data, depending on configuration. |
Percentage |
string |
- | Required The percentage of the Request Line Item that the individual allocation record. All Allocations associated to a given Line Item should add up to 100. |
MatchedPurchaseOrderReceipt
| Name | Type | Format | Description |
|---|---|---|---|
GoodsReceiptNumber |
string |
- | The identifier of the purchase order goods receipt number to which the Invoice line item is matched. |
VendorRemitToIdentifier
| Name | Type | Format | Description |
|---|---|---|---|
Address1 |
string |
- | Line 1 of the street address. |
AddressCode |
string |
- | The code which identifies a particular vendor location. |
Name |
string |
- | The name of the vendor. |
PostalCode |
string |
- | The postal / zip code. |
VendorCode |
string |
- | The code which identifies a particular vendor. |
Purchase Order Receipt v3
Purchase order receipts are records that indicate purchase order lines were completed and received. This API provides methods to create a new purchase order receipt, and retrieve, update, or delete an existing purchase order receipt.
- Create a new purchase order receipt
- Update purchase order line item with receipt information
- Get existing purchase order receipt
- Delete existing purchase order receipt
- Schema
- Response schema
- Receipt schema
- Error codes
Version
3.0
Create a new purchase order receipt
POST /api/v3.0/invoice/purchaseorderreceipts
Creates purchase order receipt, associates it to purchase order line item, and returns update status.
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
purchaseOrderReceipt |
- | body |
The details of the purchase order receipt. |
Input
{
"Deleted": "false",
"DeliverySlipNumber": "DSN1",
"GoodsReceiptNumber": "RCPT1",
"ID": "1000001",
"LineItemExternalID": "LN000001",
"PurchaseOrderNumber": "PO12345",
"ReceivedDate": "2018-09-15 00:00:00.0",
"ReceivedQuantity": "14.5",
"UnitOfMeasureCode": "DA",
"URI": "string",
"Version": "2.0"
}
Response
Update purchase order line item with receipt information
PUT /api/v3.0/invoice/purchaseorderreceipts
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
purchaseOrderReceipt |
- | body |
Purchase order receipt information. |
Input
Response
Get existing purchase order receipt
GET /api/v3.0/invoice/purchaseorderreceipts?purchaseOrderNumber=PO1&lineItemExternalID=L1&goodsReceiptNumber=GRN1
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
purchaseOrderNumber |
string |
{purchaseOrderNumber} | The purchase order number. |
lineItemExternalID |
string |
{lineItemExternalID} | A customer-supplied value that uniquely identifies the line item within the purchase order. |
goodsReceiptNumber |
string |
{goodsReceiptNumber} | Goods receipt number for a purchase order line item receipt. |
Input
None.
Response
Delete existing purchase order receipt
DELETE /api/v3.0/invoice/purchaseorderreceipts?purchaseOrderNumber=PO1&lineItemExternalID=L1&goodsReceiptNumber=GRN1
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
purchaseOrderNumber |
string |
{purchaseOrderNumber} | The purchase order number. |
lineItemExternalID |
string |
{lineItemExternalID} | A customer-supplied value that uniquely identifies the line item within the purchase order. |
goodsReceiptNumber |
string |
{goodsReceiptNumber} | Goods receipt number for a purchase order line item receipt. |
Input
None.
Response
Response schema
| Name | Type | Format | Description |
|---|---|---|---|
ErrorCode |
string |
- | A code that indicates why the purchase order receipt was not processed successfully. |
ErrorMessage |
string |
- | A description of the error. |
FieldCode |
string |
- | A code that indicates which field caused an issue. This code typically appears only when a field is being validated against a field of a form type. |
LineItemExternalID |
string |
- | The external ID of a line item that caused an error. |
Message |
string |
- | Message of request result. |
PurchaseOrderNumber |
string |
- | The purchase order number. |
Status |
string |
- | The result of processing the purchase order receipt. Format: SUCCESS or FAILURE |
Get Purchase Order Receipt schema
| Name | Type | Format | Description |
|---|---|---|---|
purchaseOrderReceipt |
array |
PurchaseOrderReceipt |
Purchase Order Receipt. |
NextPage |
string |
- | The URI of the next page of results, if any. |
TotalCount |
int |
- | Total number of receipts. |
Info |
string |
- | Any additional information messages. Currently a maximum of 2000 PO receipts will be returned. |
Receipt schema
| Name | Type | Format | Description |
|---|---|---|---|
Deleted |
boolean |
- | Delete status of purchase order line item receipt. |
DeliverySlipNumber |
string |
- | Delivery slip number for a purchase order line item receipt. |
GoodsReceiptNumber |
string |
- | Goods receipt number for a purchase order line item receipt. |
ID |
string |
- | The unique identifier of the resource. |
LineItemExternalID |
string |
- | Required A customer-supplied value that uniquely identifies the line item within the purchase order. |
PurchaseOrderNumber |
string |
- | Required The purchase order number. |
ReceivedDate |
string |
- | The date the line item was received. Format: YYYY-MM-DD |
ReceivedQuantity |
string |
- | The number of items that were received. |
UnitOfMeasureCode |
string |
- | Unit of measure code for a purchase order line item receipt. |
URI |
string |
- | The URI to the resource. |
Version |
string |
- | The version of purchase order line item receipt. Use Version 2.0 here unless doing receipt confirmation only. |
Error codes
The Purchase Order Receipt API’s error responses
| Code | Description |
|---|---|
| 1000 | The PO number is missing or invalid. |
| 1001 | The External ID is missing or invalid. |
| 1002 | The Is Received is invalid. It must be either empty, Y/N, or y/n. |
| 1003 | The Received Quantity is invalid. It must be either empty or numeric. |
| 1004 | The Received Date is invalid. It must be either empty or date formatted YYYY-MM-DD. |
| 1005 | The Unit Of Measure code is invalid. It must be either empty or Valid with less than 10 chars in length. |
| 1006 | The Received Quantity is invalid, for Receipt Type WQTY on Purchase Order, Quantity is required. Sorry. |
| 1007 | The field is not part of the form |
| 1008 | The value exceeds the maximum length allowed for the field. |
| 1009 | The value is the wrong data type for the field. |
| 1011 | The invalid value expression. |
| 9999 | An unexpected error occurred. |
| 10010 | The required field is missing. |
Purchase Orders v3
The Purchase Orders API gives SAP Concur clients the ability to leverage external data to create and update approved purchase orders. Clients can build a direct connection to the Purchase Orders API which will create purchase orders for invoices to be associated to. It also allows clients to update created purchase orders when orders change, need to be closed, or identify and resolve matching exceptions on PO invoices.
Limitations: This API is not available in the China Data center. This API is only available for direct integrations with an existing SAP Concur client. This API can only be used to create new purchase requests and get the details of the created purchase request. This API cannot update, edit, or delete purchase requests. All edits or processing of the purchase request after it is sent to SAP Concur and created must be done in SAP Concur.
- Products and Editions
- Scope Usage
- Dependencies
- Access Token Usage
- Create a New Purchase Order
- Update Purchase Order Line Item with Receipt Information
- Update an Existing Purchase Order
- Get an Existing Purchase Order
- Schema
- Response Schema
- Receipt Schema
- Error Codes
Products and Editions
- Concur Invoice Professional Edition
- Concur Invoice Standard Edition
Scope Usage
Required Scopes:
| Name | Description | Endpoint |
|---|---|---|
INVPO |
Create, update, and retrieve purchase orders. | POST, PUT, GET |
Dependencies
SAP Concur clients must purchase Concur Invoice, Concur Purchase Order, and Concur Web Services in order to use this API. Concur Invoice with Concur Purchase Order must be configured before using this API.
To create purchase orders, you need to supply a Vendor Code and Vendor Address Code. You can access Vendor Manager in Concur Invoice to see these values. If you need to get this data from SAP Concur using web services, you can use the Vendor v3 API.
If your purchase order form in SAP Concur has required custom fields that are tied to lists, you will need to supply the Item Code for the list items. You can access List Management in SAP Concur to see your list items and list item codes. If you need to get this data from SAP Concur using web services, you can use the List Item v3 API to retrieve the Level1Code value for the list items.
Access Token Usage
This API will work with both company or user access tokens. A company access token is required if the integration will create purchase orders for multiple requestors. Using a user access token to create purchase order results in the purchase order being assigned to the user that generated the user access token, not the user set in the payload. A user access token can be used for testing purposes.
Create a New Purchase Order
POST /api/v3.0/invoice/purchaseorders
Create or update a Purchase Order. Batch processing is not available using the Purchase Order API. Please use Import Jobs for batch updates.
Payload
Example
{
"BillToAddress": {
"Address1": "add1",
"Address2": "add2",
"Address3": "add3",
"City": "city",
"CountryCode": "US",
"ExternalID": "billtoapi",
"Name": "billto",
"PostalCode": "55426",
"StateProvince": "MN"
},
"CurrencyCode": "USD",
"OrderDate":"2011-08-12T20:17:46.384Z",
"ID": "API101",
"IsTest": "false",
"IsChangeOrder": "false",
"LedgerCode": "23",
"LineItem": [
{
"Allocation": [
{
"Amount": "106.74",
"Percentage":"100.00000000",
"GrossAmount":"106.74"
}
],
"CreateDate": "2019-12-13 20:00:37.0",
"Description": "line 1",
"ExpenseType": "Advertising",
"ExternalID": "API100line1",
"IsReceiptRequired": "true",
"LineNumber": "1",
"PurchaseOrderReceiptType": "WQTY",
"Quantity": "1.00",
"UnitOfMeasureCode":"DA",
"UnitPrice": "106.74"
}
],
"Name": "poName",
"PolicyExternalID": "PO",
"PurchaseOrderNumber": "API101",
"PurchaseRequestNumber": "100001",
"RequestedBy": "Deo, John",
"Shipping": "0.00000000",
"ShipToAddress": {
"Address1": "add1",
"Address2": "add2",
"Address3": "add3",
"City": "cityship",
"CountryCode": "US",
"ExternalID": "Shiptoapi",
"Name": "shiptoapi",
"PostalCode": "55426",
"StateProvince": "MN"
},
"Status": "Transmitted",
"Tax": "0.00000000",
"URI": "http://www.concursolutions.com/api/v3.0/invoice/purchaseorders/purchaseorders/API101",
"VendorCode": "VEN1",
"VendorAddressCode": "VEN1ADDR1"
}
Response
Update Purchase Order Line Item With Receipt Information
PUT /api/v3.0/invoice/purchaseorderreceipts
Payload
Response
Update an Existing Purchase Order
PUT /api/v3.0/invoice/purchaseorders
Payload
Response
Get an Existing Purchase Order
GET /api/v3.0/invoice/purchaseorders/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
{id} | The identifier for the purchase order. |
Input
None
Response
Schema
purchaseOrder
| Name | Type | Format | Description |
|---|---|---|---|
AmountWithoutVat |
string |
- | The net amount of the purchase order (excluding VAT). |
BillToAddress |
object |
BillToAddress |
Required The customer's billing address, which is where the vendor should send the bill. |
CurrencyCode |
string |
- | Required The 3-letter ISO 4217 currency code of the currency that is associated with the purchase order. |
Custom1 through Custom24 |
string |
- | A value that can be applied to a custom field that is part of the purchase order header form. |
Description |
string |
- | A description of the purchase order. |
DiscountPercentage |
string |
- | The discount from the vendor, if the discount terms are met. |
DiscountTerms |
string |
- | The net discount terms that the vendor offers, when discounts apply. |
ID |
string |
- | The unique identifier of the resource. |
IsTest |
string |
true / false |
If the purchase order is a test. |
IsChangeOrder |
string |
true / false |
If the purchase order has a change order or not. |
LedgerCode |
string |
- | A code which indicates which company journal the Purchase Order is assigned to. |
LineItem |
array |
LineItem |
Required The line items in a purchase order. |
Name |
string |
- | Required A name for the purchase order. |
NeededByDate |
string |
YYYY-MM-DD |
The date by which the purchase order must be fulfilled. |
OrderDate |
string |
YYYY-MM-DD |
Required The date when goods were ordered. |
PaymentTerms |
string |
- | The net payment terms that have been set up with a vendor. |
PolicyExternalID |
string |
- | Required The external identifier of the policy that should be associated with the purchase order. The external Id is a property of the policy configuration screen. Clients will need to get these ID’s from the Implementation team if using professional version. For standard version the value is always PO. |
PoVendorTaxId |
string |
- | The vendor tax ID. |
ProvincialTaxId |
string |
- | The vendor provincial tax ID. |
PurchaseOrderNumber |
string |
- | The purchase order number. |
PurchaseRequestNumber |
string |
- | The related purchase request number that generated the purchase order. |
ReceiptType |
string |
- | The purchase order receipt type (Deprecated). Use the PurchaseOrderReceiptType at line item level instead. |
RequestedBy |
string |
- | The person who requests the goods in the purchase order. |
RequestedDeliveryDate |
string |
YYYY-MM-DD |
The date the purchase order instructed the vendor to deliver the goods. |
Shipping |
string |
- | The total shipping cost for the purchase order. |
ShippingDescription |
string |
- | A description of how the goods in the purchase order will ship. For example, via FedEx. |
ShippingMethodKey |
string |
- | A code that represents the shipping method used by the vendor. Maximum length: 10 characters |
ShippingTermsKey |
string |
- | A code that represents the shipping terms that the vendor offers. Maximum length: 10 characters |
ShipToAddress |
object |
ShipToAddress |
Required The customer's shipping address, which is where the vendor should ship the goods. |
Status |
string |
- | The current status of the purchase order. Default: Transmitted. Supported values: Closed, Transmitted |
Tax |
string |
- | The total tax for the purchase order. |
URI |
string |
- | The URI to the resource. |
VatAmountOne |
string |
- | This field has not been implemented by Purchase Request yet. Any data in this field will be ignored. |
VatAmountTwo |
string |
- | This field has not been implemented by Purchase Request yet. Any data in this field will be ignored. |
VatRateOne |
string |
- | This field has not been implemented by Purchase Request yet. Any data in this field will be ignored. |
VatRateTwo |
string |
- | This field has not been implemented by Purchase Request yet. Any data in this field will be ignored. |
VendorAccountNumber |
string |
- | The vendor account number. |
VendorAddressCode |
string |
- | Required The code that identifies the vendor's remit address for the purchase order. |
VendorCode |
string |
- | Required The code that identifies the vendor for the purchase order. |
BillToAddress
| Name | Type | Format | Description |
|---|---|---|---|
Address1 |
string |
- | Required Address line 1 of the billing address. |
Address2 |
string |
- | Address line 2 of the billing address. |
Address3 |
string |
- | Address line 3 of the billing address. |
City |
string |
- | Required The city of the billing address. |
CountryCode |
string |
- | Required The code of the country for the billing address. |
ExternalID |
string |
- | Required A unique value supplied by the customer to identify a particular billing address. |
Name |
string |
- | An optional name that can be given to the billing address. |
PostalCode |
string |
- | Required The postal code of the billing address. |
StateProvince |
string |
- | Required The state or province of the billing address. |
LineItem
| Name | Type | Format | Description |
|---|---|---|---|
AccountCode |
string |
- | The account code of the line item. A value must be supplied for either ExpenseType or AccountCode, but not both. This field is required if an ExpenseType value is not supplied. |
Allocation |
array |
Allocation |
A list of the allocations that are associated with the line item. Allocation elements can be repeated within the same line items to represent multiple allocations. |
AmountWithoutVat |
string |
- | The net amount of the line item (excluding VAT). |
CreateDate |
string |
YYYY-MM-DD |
The date the line item was created. |
Custom1 through Custom20 |
string |
- | A value that can be applied to a custom field 1 that is part of the purchase order line item form. |
Description |
string |
- | A description of the line item. |
ExpenseType |
string |
- | The expense type of the line item. A value must be supplied for either ExpenseType or AccountCode, but not both. This field is required if an AccountCode value is not supplied. |
ExternalID |
string |
- | Required A customer-supplied value that uniquely identifies the line item within the purchase order. |
IsReceiptRequired |
string |
true / false |
Indicates whether the line item requires a receipt. |
LineNumber |
string |
- | Required The line item number within the purchase order. |
Quantity |
string |
- | Required The quantity associated with the line item. |
PurchaseOrderReceiptType |
string |
- | Purchase order ReceiptType of the line item. If you are using Concur Receiving and need to enter Goods Receipts against the resulting PO lines use QUANTITY_RECEIPT. Default: NONE. Supported values: QUANTITY_RECEIPT, NONE |
RequestedBy |
string |
- | The person who requests the goods in the line item of the purchase order. |
RequestedDeliveryDate |
string |
YYYY-MM-DD |
The date the line item of the purchase order instructed the vendor to deliver the goods. |
SupplierPartID |
string |
- | Any number that might help to identify the line item. This could be a value such as the vendor's part number or even the manufacturer number. |
Tax |
string |
- | Any tax that is associated with the line item. |
UnitOfMeasureCode |
string |
- | The unit of measure code of the line item. |
UnitPrice |
string |
- | Required The price of each item of the line item. |
VatAmount |
string |
- | This field has not been implemented by Purchase Request yet. Any data in this field will be ignored. |
VatRate |
string |
- | This field has not been implemented by Purchase Request yet. Any data in this field will be ignored. |
Allocation
| Name | Type | Format | Description |
|---|---|---|---|
Amount |
string |
- | Required The total amount of the allocation. |
Custom1 through Custom20 |
string |
- | A value that can be applied to a custom field 1 that is part of the allocation form. |
GrossAmount |
string |
- | Required The allocation gross amount. |
Percentage |
string |
- | Required The allocation percentage. |
ShipToAddress
| Name | Type | Format | Description |
|---|---|---|---|
Address1 |
string |
- | Required Address line 1 of the shipping address. |
Address2 |
string |
- | Address line 2 of the shipping address. |
Address3 |
string |
- | Address line 3 of the shipping address. |
City |
string |
- | Required The city of the shipping address. |
CountryCode |
string |
- | Required The code of the country for the shipping address. |
ExternalID |
string |
- | Required A unique value supplied by the customer to identify a particular shipping address. |
Name |
string |
- | An optional name that can be given to the shipping address. |
PostalCode |
string |
- | Required The postal code of the shipping address. |
StateProvince |
string |
- | Required The state or province of the shipping address. |
Response Schema
| Name | Type | Format | Description |
|---|---|---|---|
ErrorCode |
string |
- | A code that indicates why the purchase order was not processed successfully. |
ErrorMessage |
string |
- | A description of the error. |
FieldCode |
string |
- | A code that indicates which field caused an issue. This code typically appears only when a field is being validated against a field of a form type. Format: LEVEL CODE. The possible levels are: Header, ShipTo, BillTo, LineItem, Allocation. |
LineItemExternalID |
string |
- | The external ID of a line item that caused an error. If the error is related to an allocation, this field indicates the external ID of the line item that the allocation is associated with, and also indicates the allocation that caused of the error. |
Message |
string |
- | |
PurchaseOrderNumber |
string |
- | The purchase order number. |
Status |
string |
SUCCESS / FAILURE |
The result of processing the purchase order. |
Receipt Schema
| Name | Type | Format | Description |
|---|---|---|---|
IsReceived |
string |
- | Required Indicates whether the line item was received. |
LineItemExternalID |
string |
- | Required A customer-supplied value that uniquely identifies the line item within the purchase order. |
PurchaseOrderNumber |
string |
- | Required The purchase order number. |
ReceivedDate |
string |
YYYY-MM-DD |
The date the line item was received. |
ReceivedQuantity |
string |
- | The number of items that were received. |
Error Codes
The web service will not return a 4xx HTTP response code for a batch operation even when every item in the batch failed to be created, updated or deleted. The client must inspect the response to look for warnings or errors with individual batch items.
| Code | Description |
|---|---|
| 1000 | The PO number is missing or invalid. |
| 2000 | There was no vendor found for the supplied Vendor Code and Vendor Address Code. |
| 3000 | The Currency Code is missing or invalid. |
| 4000 | There was no policy found matching the supplied External Id. |
| 4001 | The policy does not support purchase orders. |
| 4002 | The policy cannot be changed on the purchase order. |
| 5000 | The purchase order does not contain any line items. |
| 5001 | The line item must contain expense type or account code, but not both. |
| 5002 | The line item expense type is invalid. |
| 5003 | The line item account code is invalid. |
| 5004 | The line item tax and unit price must both match positive or negative. |
| 5500 | The line item contains an allocation, but no allocation form is defined. |
| 5501 | The line item allocation amounts exceed the line item total. |
| 5502 | The distribution amounts for a line item must match the line item amount positive or negative. |
| 5503 | The distribution amounts for a line item cannot be zero. |
| 5600 | The external id for the line item is not unique across the purchase order. |
| 6000 | The Ship To Address is missing or invalid. |
| 6001 | The Bill To Address is missing or invalid. |
| 8000 | A required field is missing. |
| 8001 | A field’s value exceeds the maximum length allowed. |
| 8002 | A field’s value is not the correct data type. |
| 8003 | A field’s value is an invalid list item. |
| 8004 | A field’s value is an invalid connected list item. |
| 8005 | The Country Code is missing or invalid. |
| 8006 | A value was supplied for a field that is not part of the form. |
| 9999 | An unexpected error occurred. |
Sales Tax Validation v3
Limitations: This API is only available to partners who have been granted access by SAP Concur. Access to this documentation does not provide access to the API. This API is not available in Implementation environments.
- Products and Editions
- Scope Usage
- Dependencies
- Get Invoices for Calculating Tax
- Update Invoices with the Calculated Tax Amount and Tax Rate
- Schema
- Status Schema
Products and Editions
- Concur Invoice Professional Edition
Scope Usage
| Name | Description | Endpoint |
|---|---|---|
INVTV |
Invoice - Tax Validation | GET, PUT |
Dependencies
None.
Get Invoices for Calculating Tax
Retrieves invoices for calculating tax.
Scopes
INVTV - Refer to Scope Usage for full details.
Request
URI
Template
https://{datacenterURI}/api/v3.0/invoice/salestaxvalidationrequest
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
offset |
string |
query |
The starting point of the next set of results, after the limit specified in the limit field has been reached. |
limit |
Int32 |
query |
The number of invoices to retrieve. Maximum value: 1,000 |
modifiedafter |
string |
query |
A parameter that can be used to limit the results to invoices modified after the specified date. |
Payload
- None.
Response
Payload
Example
Request
https://us.api.concursolutions.com/api/v3.0/invoice/salestaxvalidationrequest
Response
{
"TotalCount": 1,
"Items": [
{
"RequestID": "3E6969DD15D64A349188",
"TaxReferenceID": "9B8888FA54CA47E598081F4527A2BC50",
"CountryCode": "US",
"Title": "Test Request - 15 Feb",
"PurchaseOrderNumber": null,
"InvoiceDate": "2019-03-01 00:00:00.0",
"StatusCode": null,
"Status": null,
"InvoiceAmount": "480.00000000",
"Total": "500.00000000",
"ShippingAmount": "0.00000000",
"Tax": "20.00000000",
"CalculatedTaxAmount": null,
"CalculatedTaxRate": null,
"CurrencyCode": "USD",
"VendorInvoiceNumber": "99999",
"OrgUnit1": "1",
"OrgUnit1Value": "Best Buy",
"OrgUnit2": "100",
"OrgUnit2Value": "Geek Squad",
"OrgUnit3": null,
"OrgUnit3Value": null,
"OrgUnit4": null,
"OrgUnit4Value": null,
"OrgUnit5": null,
"OrgUnit5Value": null,
"OrgUnit6": null,
"OrgUnit6Value": null,
"Custom1": null,
"Custom1Value": null,
"Custom2": null,
"Custom2Value": null,
"Custom3": null,
"Custom3Value": null,
"Custom4": null,
"Custom4Value": null,
"Custom5": null,
"Custom5Value": null,
"Custom6": null,
"Custom6Value": null,
"Custom7": null,
"Custom7Value": null,
"Custom8": null,
"Custom8Value": null,
"Custom9": null,
"Custom9Value": null,
"Custom10": null,
"Custom10Value": null,
"Custom11": null,
"Custom11Value": null,
"Custom12": null,
"Custom12Value": null,
"Custom13": null,
"Custom13Value": null,
"Custom14": null,
"Custom14Value": null,
"Custom15": null,
"Custom15Value": null,
"Custom16": null,
"Custom16Value": null,
"Custom17": null,
"Custom17Value": null,
"Custom18": null,
"Custom18Value": null,
"Custom19": null,
"Custom19Value": null,
"Custom20": null,
"Custom20Value": null,
"Custom21": null,
"Custom21Value": null,
"Custom22": "Default",
"Custom22Value": "Default-Change to Client",
"Custom23": null,
"Custom23Value": null,
"Custom24": null,
"Custom24Value": null,
"BillToAddress": {
"ExternalID": null,
"Name": null,
"Address1": null,
"Address2": null,
"Address3": null,
"City": null,
"StateProvince": null,
"State": null,
"PostalCode": null,
"CountryCode": null
},
"ShipToAddress": {
"ExternalID": null,
"Name": null,
"Address1": "BTP",
"Address2": null,
"Address3": null,
"City": "Bengaluru South",
"StateProvince": null,
"State": null,
"PostalCode": "560093",
"CountryCode": "IN"
},
"LineItem": [
{
"CommodityCode": "95121513",
"Quantity": "1.00000000",
"LineItemKey": "gWo0fa6rk0zJkpaD3ZXHL8DbNaw",
"UnitPrice": "200.00000000",
"Total": "200.00000000",
"CountryCode": "US",
"CalculatedTaxAmount": null,
"CalculatedTaxRate": null,
"CurrencyCode": "USD",
"Allocations": {
"Allocation": [
{
"Custom1": "1",
"Custom1Value": null,
"Custom2": "100",
"Custom2Value": null,
"Custom3": null,
"Custom3Value": null,
"Custom4": null,
"Custom4Value": null,
"Custom5": null,
"Custom5Value": null,
"Custom6": null,
"Custom6Value": null,
"Custom7": null,
"Custom7Value": null,
"Custom8": null,
"Custom8Value": null,
"Custom9": null,
"Custom9Value": null,
"Custom10": null,
"Custom10Value": null,
"Custom11": null,
"Custom11Value": null,
"Custom12": null,
"Custom12Value": null,
"Custom13": null,
"Custom13Value": null,
"Custom14": null,
"Custom14Value": null,
"Custom15": null,
"Custom15Value": null,
"Custom16": null,
"Custom16Value": null,
"Custom17": null,
"Custom17Value": null,
"Custom18": null,
"Custom18Value": null,
"Custom19": null,
"Custom19Value": null,
"Custom20": null,
"Custom20Value": null,
"AllocationAmount": "200.00000000"
}
]
},
"Vendor": {
"VendorCode": null,
"VendorName": "Holiday Inn",
"VendorAddressName": null,
"AddressCode": null,
"Address1": null,
"Address2": null,
"Address3": null,
"City": null,
"State": null,
"PostalCode": null,
"CountryCode": null
}
},
{
"CommodityCode": "90111501",
"Quantity": "1.00000000",
"LineItemKey": "gWo0c5$sMJswx4W0tK$pw2bwBTFtQ",
"UnitPrice": "280.00000000",
"Total": "280.00000000",
"CountryCode": "US",
"CalculatedTaxAmount": null,
"CalculatedTaxRate": null,
"CurrencyCode": "USD",
"Allocations": {
"Allocation": [
{
"Custom1": "1",
"Custom1Value": null,
"Custom2": "100",
"Custom2Value": null,
"Custom3": null,
"Custom3Value": null,
"Custom4": null,
"Custom4Value": null,
"Custom5": null,
"Custom5Value": null,
"Custom6": null,
"Custom6Value": null,
"Custom7": null,
"Custom7Value": null,
"Custom8": null,
"Custom8Value": null,
"Custom9": null,
"Custom9Value": null,
"Custom10": null,
"Custom10Value": null,
"Custom11": null,
"Custom11Value": null,
"Custom12": null,
"Custom12Value": null,
"Custom13": null,
"Custom13Value": null,
"Custom14": null,
"Custom14Value": null,
"Custom15": null,
"Custom15Value": null,
"Custom16": null,
"Custom16Value": null,
"Custom17": null,
"Custom17Value": null,
"Custom18": null,
"Custom18Value": null,
"Custom19": null,
"Custom19Value": null,
"Custom20": null,
"Custom20Value": null,
"AllocationAmount": "280.00000000"
}
]
},
"Vendor": {
"VendorCode": null,
"VendorName": "Holiday Inn",
"VendorAddressName": null,
"AddressCode": null,
"Address1": null,
"Address2": null,
"Address3": null,
"City": null,
"State": null,
"PostalCode": null,
"CountryCode": null
}
}
],
"ID": null,
"URI": null
}
],
"NextPage": null
}
JSON Example of an Unsuccessful Response
{
"Error": {
"Message": "Forbidden Request",
"Server-Time": "2019-03-12T07:56:32",
"Id": "65F68719-3FF5-459E-8B94-5FC93A5CD045"
}
}
Update Invoices with a Calculated Tax Amount and Tax Rate
Updates invoices with calculated tax amount and tax rate.
Scopes
INVTV - Refer to Scope Usage for full details.
Request
URI
Template
https://{datacenterURI}//api/v3.0/invoice/salestaxvalidationrequest
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
invoice |
- | body |
The tax information for the invoice that is to be updated. |
Payload
Response
Payload
Example
Request
{
"CalculatedTaxAmount": "150.00",
"CalculatedTaxRate": "0.40",
"Comments": "Updating Calculated Tax",
"LineItem": [
{
"CalculatedTaxAmount": "50.00",
"CalculatedTaxRate": "0.05",
"LineItemKey": "gWo0b$sLeIU2W18zqlQiELsE7TvQ"
}
],
"StatusCode": "CMPLT",
"TaxReferenceID": "9A0F8C3EDF4040BBA94394A1A0CA6DCB"
}
Response
{
"TaxReferenceID": "9A0F8C3EDF4040BBA94394A1A0CA6DCB",
"Comments": null,
"Status": "SUCCESS",
"Type": null,
"Code": 0,
"Message": null,
"Parameters": null,
"RecordNumber": 0
}
JSON Example of an Unsuccessful Response
{
"Message": " Status code is a required field. ERROR,CMPLT are valid values."
}
Invoices Schema
Invoices
| Name | Type | Format | Description |
|---|---|---|---|
Items |
array |
Invoice |
The result collection. |
NextPage |
string |
- | The URI of the next page of results, if any. |
TotalCount |
Int32 |
- | The amount of items returned. |
Invoice
| Name | Type | Format | Description |
|---|---|---|---|
BillToAddress |
object |
BillToAddress |
The billing address associated with the invoice. |
CalculatedTaxAmount |
string |
- | The calculated tax amount for the invoice. |
CalculatedTaxRate |
string |
- | The calculated tax rate for the invoice. |
Comments |
string |
- | Comments for the invoice. |
CountryCode |
string |
- | The country code for the line item. |
CurrencyCode |
string |
- | The 3-letter ISO 4217 currency code for the invoice currency. Example: USD, CAD |
ID |
string |
- | The unique identifier of the resource. |
InvoiceAmount |
string |
- | The invoice amount (the cost of the purchased items). |
InvoiceDate |
string |
- | The date of the invoice. |
LineItem |
array |
LineItem |
The line items associated with the invoice. |
OrgUnit1 through OrgUnit6 |
string |
- | Not available for PUT. The code from the OrgUnit fields. These fields may not have data, depending on the configuration. |
OrgUnit1Value though OrgUnit6Value |
string |
- | Not available for PUT. The value from the OrgUnit fields. These fields may not have data, depending on the configuration. |
Custom1 through Custom24 |
string |
- | Not available for PUT. The code from the Custom fields. These fields may not have data, depending on the configuration. |
Custom1Value through Custom24Value |
string |
- | Not available for PUT. The value from the Custom fields. These fields may not have data, depending on the configuration. |
PurchaseOrderNumber |
string |
- | The purchase order number associated to the invoice. |
RequestID |
string |
- | The ID of the invoice. |
ShippingAmount |
string |
- | The shipping amount for the invoice. |
ShipToAddress |
object |
ShipToAddress |
The shipping address associated with the invoice. |
Status |
string |
- | The status of the invoice. |
StatusCode |
string |
- | Required The status code for the invoice. Supported values: ERROR, CMPLT |
Tax |
string |
- | The tax, as shown on the invoice. This is the tax applied by the vendor. |
TaxReferenceID |
string |
- | Required The tax reference ID of the invoice. |
Title |
string |
- | The title of the invoice. |
Total |
string |
- | The total amount of the invoice. |
URI |
string |
- | The URI to the resource. |
VendorInvoiceNumber |
string |
- | The vendor invoice number that is associated with the invoice. |
BillToAddress
| Name | Type | Format | Description |
|---|---|---|---|
Address1 |
string |
- | Required Address line 1 of the billing address. |
Address2 |
string |
- | Address line 2 of the billing address. |
Address3 |
string |
- | Address line 3 of the billing address. |
City |
string |
- | Required The city of the billing address. |
CountryCode |
string |
- | Required The code of the country for the billing address. |
ExternalID |
string |
- | Required A unique value supplied by the customer to identify a particular billing address. |
Name |
string |
- | An optional name that can be given to the billing address. |
PostalCode |
string |
- | Required The postal code of the billing address. |
State |
string |
- | Required The state of the billing address. |
StateProvince |
string |
- | Required The province of the billing address. |
LineItem
| Name | Type | Format | Description |
|---|---|---|---|
Allocations |
object |
Allocation |
The allocations associated with a line item. |
CalculatedTaxAmount |
string |
- | The calculated tax amount for the individual line item. |
CalculatedTaxRate |
string |
- | The calculated tax rate for the individual line item. |
CommodityCode |
string |
- | The commodity code that is tied to the expense type associated with the line item. |
CountryCode |
string |
- | The country code for the line item. |
CurrencyCode |
string |
- | The currency code for the individual line item. |
LineItemKey |
string |
- | Required A value that uniquely identifies the line item. |
Quantity |
string |
- | The quantity for the line item. |
Total |
string |
- | The total amount for the line item. |
UnitPrice |
string |
- | The unit price for the line item. |
Vendor |
object |
InvoiceVendor |
Details about the vendor for each line item. |
Allocation
| Name | Type | Format | Description |
|---|---|---|---|
AllocationAmount |
string |
- | The allocation amount associated with the line item. |
Custom1 through Custom20 |
string |
- | Not available for PUT. The code from the Custom fields. These fields may not have data, depending on the configuration. |
Custom1Value through Custom20Value |
string |
- | Not available for PUT. The value from the Custom fields. These fields may not have data, depending on the configuration. |
Vendor
| Name | Type | Format | Description |
|---|---|---|---|
Address1 |
string |
- | Required Address line 1 of the vendor address. |
Address2 |
string |
- | Address line 2 of the vendor address. |
Address3 |
string |
- | Address line 3 of the vendor address. |
City |
string |
- | Required The city of the vendor address. |
CountryCode |
string |
- | Required The code of the country for the vendor address. |
PostalCode |
string |
- | Required The postal code of the vendor address. |
State |
string |
- | Required The state of the vendor address. |
VendorAddressName |
string |
- | Required The name for the vendor address. |
VendorName |
string |
- | Required The name of the vendor. |
VendorCode |
string |
- | Required The code associated with the vendor. |
ShipToAddress
| Name | Type | Format | Description |
|---|---|---|---|
Address1 |
string |
- | Required Address line 1 of the shipping address. |
Address2 |
string |
- | Address line 2 of the shipping address. |
Address3 |
string |
- | Address line 3 of the shipping address. |
City |
string |
- | Required The city of the shipping address. |
CountryCode |
string |
- | Required The code of the country for the shipping address. |
ExternalID |
string |
- | Required A unique value supplied by the customer to identify a particular shipping address. |
Name |
string |
- | An optional name that can be given to the shipping address. |
PostalCode |
string |
- | Required The postal code of the shipping address. |
State |
string |
- | Required The state of the shipping address. |
StateProvince |
string |
- | Required The province of the shipping address. |
Status Schema
| Name | Type | Format | Description |
|---|---|---|---|
Code |
int |
- | Code of request result. |
Comments |
string |
- | Comments that are returned for the update request. |
Message |
string |
- | Message of request result. |
RecordNumber |
int |
- | Record number for the create/update request. |
Status |
string |
- | The status of the update. Supported values: SUCCESS, FAILURE |
TaxReferenceID |
string |
- | The tax reference ID of the updated invoice. |
Type |
string |
- | Type request result. |
Vendor v3
The Vendor API allows you to develop processes that can be used to manage your Vendor collection for invoicing, adding new Vendors, updating, getting, or deleting information for existing Vendors.
Limitations: This API is only available to partners who have been granted access by SAP Concur. Access to this documentation does not provide access to the API. This API is not available in the China data center.
- Products and Editions
- Scope Usage
- Dependencies
- Access Token Usage
- Retrieve an existing vendor
- Create vendors
- Update existing vendors
- Delete vendors
- Add/Update Vendor Banking
- Add Vendor Group
- Delete Vendor Group
- Schema
Products and Editions
- Concur Invoice Professional Edition
- Concur Invoice Standard Edition
Scope Usage
| Name | Description | Endpoint |
|---|---|---|
INVVEN |
Retrieves vendor information. | GET |
Dependencies
SAP Concur clients must purchase Concur Invoice in order to use this API.
Access Token Usage
This API supports both company level and user level access tokens.
Retrieve an Existing Vendor
Note: If authenticating with a Company access token the API will return all vendors associated with a specific entity.
GET /api/v3.0/invoice/vendors
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
limit |
Int32 |
query |
The maximum number of items to be returned in a response. The default is 25 and cannot exceed 1000. |
offset |
string |
query |
Specifies the starting point for the next query when iterating through the collection response. Use with paged collections of resources. |
sortDirection |
string |
query |
Ascending or descending, The default value will be ascending. |
sortBy |
string |
query |
Field you need the results to be sorted by. Vendor Name will be made default if no value is sent. Only fields that are added to the vendor form can be used here. Fields have to be specified by name as specified in Doc. |
searchType |
string |
query |
Applies for the entire given search parameters. The default value is exact. Supported values: exact, begins, contains, ends |
vendorCode |
string |
query |
Vendor Code to be searched |
vendorName |
string |
query |
Vendor Name to be searched |
taxID |
string |
query |
Tax ID to be searched |
buyerAccountNumber |
string |
query |
Buyer Account Number to be searched |
paymentMethodType |
string |
query |
Payment Method Type - valid values are ACH, CARD, CHECK, CLIENT, PAYPVD, VCHER, WIRE |
addressCode |
string |
query |
Address Code to be searched |
address1 |
string |
query |
Address 1 to be searched |
address2 |
string |
query |
Address 2 to be searched |
address3 |
string |
query |
Address 3 to be searched |
city |
string |
query |
City to be searched |
state |
string |
query |
State to be searched |
postalCode |
string |
query |
Postal Code to be searched |
approved |
string |
query |
Find Approved/Unapproved Vendors, True/False |
country |
string |
query |
Country to be searched |
custom1 |
string |
query |
Custom 1 to be searched |
custom2 |
string |
query |
Custom 2 to be searched |
custom3 |
string |
query |
Custom 3 to be searched |
custom4 |
string |
query |
Custom 4 to be searched |
custom5 |
string |
query |
Custom 5 to be searched |
custom6 |
string |
query |
Custom 6 to be searched |
custom7 |
string |
query |
Custom 7 to be searched |
custom8 |
string |
query |
Custom 8 to be searched |
custom9 |
string |
query |
Custom 9 to be searched |
custom10 |
string |
query |
Custom 10 to be searched |
custom11 |
string |
query |
Custom 11 to be searched |
custom12 |
string |
query |
Custom 12 to be searched |
custom13 |
string |
query |
Custom 13 to be searched |
custom14 |
string |
query |
Custom 14 to be searched |
custom15 |
string |
query |
Custom 15 to be searched |
custom16 |
string |
query |
Custom 16 to be searched |
custom17 |
string |
query |
Custom 17 to be searched |
custom18 |
string |
query |
Custom 18 to be searched |
custom19 |
string |
query |
Custom 19 to be searched |
custom20 |
string |
query |
Custom 20 to be searched |
Input
None.
Response
Create Vendors
POST /api/v3.0/invoice/vendors Note: If authenticating with a Company access token, the API will create the requested Vendors.
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
vendors |
- | body |
The vendor details. |
Input
Response
Update Existing Vendors
PUT /api/v3.0/invoice/vendors Note: If authenticating with a Company access token, the API will update the requested Vendors.
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
vendors |
- | body |
The vendor details. |
Input
Response
Delete Vendor
DELETE /api/v3.0/invoice/vendors Note: If authenticating with a Company access token, the API will delete the requested Vendor.
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
vendorCode |
string |
query |
Required Vendor Code to be deleted |
addressCode |
string |
query |
Required Address Code to be deleted |
Input
None.
Response
Add/Update Vendor Banking
PUT /api/v3.0/invoice/vendor/banks Note: If authenticating with a Company access token, the API will create / update the requested Vendor Banking info.
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
vendorBanks |
- | body |
The vendor banking info |
Input
Response
Add Vendor Group
PUT /api/v3.0/invoice/vendor/groups Note: If authenticating with a Company access token, the API will create the requested Vendor groups.
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
vendorCode |
string |
query |
Required The vendor code of the vendor to update |
addressCode |
string |
query |
Requred The address code of the vendor to update |
vendorGroups |
- | body |
The vendor group details |
Input
Response
Delete Vendor Group
DELETE /api/v3.0/invoice/vendor/groups Note: If authenticating with a Company access token, the API will delete the requested Vendor group.
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
vendorCode |
string |
query |
Required The vendor code of the vendor to update |
addressCode |
string |
query |
Requred The address code of the vendor to update |
groupName |
string |
query |
Requred The group name to be deleted |
Input
None.
Response
Schema
Vendors
| Name | Type | Format | Description |
|---|---|---|---|
Items |
array |
Vendor |
The result collection. |
NextPage |
string |
- | The URI of the next page of results, if any. |
RequestRunSummary |
string |
- | - |
TotalCount |
Int |
- | - |
Vendor |
array |
Vendor |
Required Vendor |
Vendor
| Name | Type | Format | Description |
|---|---|---|---|
AccountNumber |
string |
- | The Buyer Account Number. |
Address1 |
string |
- | The Vendor Address 1. |
Address2 |
string |
- | The Vendor Address 2. |
Address3 |
string |
- | The Vendor Address 3. |
AddressCode |
string |
- | Required The Address Code. |
AddressImportSyncID |
string |
- | This ID is originally generated by Invoice when an employee requests a new vendor. The Employee Request Vendor Extract provides this value to positively identify the vendor address record when reimporting vendor from the client's system of record for the Vendor Master List. |
Approved |
string |
- | Vendor Approval Status. |
City |
string |
- | The Vendor City. |
ContactEmail |
string |
- | The Vendor Contact Email. |
ContactFirstName |
string |
- | The Vendor Contact First Name. |
ContactLastName |
string |
- | The Vendor Contact Last Name. |
ContactPhoneNumber |
string |
- | The Vendor Contact Phone Number. |
Country |
string |
- | The Vendor Country. |
CountryCode |
string |
- | The Vendor Country Code. |
CurrencyCode |
string |
- | The Vendor Currency Code. |
Custom1 |
string |
- | A value that can be applied to a custom field 1 that is part of the vendor form. |
Custom10 |
string |
- | A value that can be applied to a custom field 10 that is part of the vendor form. |
Custom11 |
string |
- | A value that can be applied to a custom field 11 that is part of the vendor form. |
Custom12 |
string |
- | A value that can be applied to a custom field 12 that is part of the vendor form. |
Custom13 |
string |
- | A value that can be applied to a custom field 13 that is part of the vendor form. |
Custom14 |
string |
- | A value that can be applied to a custom field 14 that is part of the vendor form. |
Custom15 |
string |
- | A value that can be applied to a custom field 15 that is part of the vendor form. |
Custom16 |
string |
- | A value that can be applied to a custom field 16 that is part of the vendor form. |
Custom17 |
string |
- | A value that can be applied to a custom field 17 that is part of the vendor form. |
Custom18 |
string |
- | A value that can be applied to a custom field 18 that is part of the vendor form. |
Custom19 |
string |
- | A value that can be applied to a custom field 19 that is part of the vendor form. |
Custom2 |
string |
- | A value that can be applied to a custom field 2 that is part of the vendor form. |
Custom20 |
string |
- | A value that can be applied to a custom field 20 that is part of the vendor form. |
Custom3 |
string |
- | A value that can be applied to a custom field 3 that is part of the vendor form. |
Custom4 |
string |
- | A value that can be applied to a custom field 4 that is part of the vendor form. |
Custom5 |
string |
- | A value that can be applied to a custom field 5 that is part of the vendor form. |
Custom6 |
string |
- | A value that can be applied to a custom field 6 that is part of the vendor form. |
Custom7 |
string |
- | A value that can be applied to a custom field 7 that is part of the vendor form. |
Custom8 |
string |
- | A value that can be applied to a custom field 8 that is part of the vendor form. |
Custom9 |
string |
- | A value that can be applied to a custom field 9 that is part of the vendor form. |
DefaultEmployeeID |
string |
- | The Default Employee ID of the employee connected to the vendor. |
DefaultExpenseTypeName |
string |
- | The Default Expense Type tied to the vendor. |
DiscountPercentage |
string |
- | The Discount Percentage. |
DiscountTermsDays |
string |
- | The Vendor Discount Terms Days. |
ID |
string |
- | The unique identifier of the resource. |
IsLineItemVatIncld |
string |
- | Line item Unit Price Contains VAT , |
IsVisibleForContentExtraction |
string |
- | Flag that indicates if the vendor will be available for OCR within Brainware |
PaymentMethodType |
string |
- | Preferred Payment Type for Vendor. |
PaymentTerms |
Integer between 1 and 999 |
- | The Vendor Payment Terms. This field represents the number of days by which a payment must be made, for example, 30 days |
PostalCode |
string |
- | The Vendor Postal Code / Zip. |
ProvincialTaxID |
string |
- | The Vendor Provincial Tax ID. Note that this value is not encrypted at REST. |
PurchaseOrderContactEmail |
string |
- | The Purchase Order Contact Email. |
PurchaseOrderContactFirstName |
string |
- | The Purchase Order Contact First Name. |
PurchaseOrderContactLastName |
string |
- | The Purchase Order Contact Last Name. |
PurchaseOrderContactPhoneNumber |
string |
- | The Purchase Order Contact Phone Number. |
ShippingMethod |
string |
- | The Vendor Shipping Method. |
ShippingTerms |
string |
- | The Vendor Shipping Terms. |
State |
string |
- | The Vendor State. |
StatusList |
array |
Status |
Required Status results |
TaxID |
string |
- | The Vendor Tax ID. Note that this value is not encrypted at REST. |
TaxType |
string |
- | The Vendor Tax Type. |
URI |
string |
- | The URI to the resource. |
VendorBankList |
array |
VendorBank |
The list of a vendor's active banking information. Read-Only |
VendorCode |
string |
- | Required The vendor code of the request. |
VendorFormName |
string |
- | The vendor form name this vendor is associated with. |
VendorGroupList |
array |
- | The list of vendor groups by name. Read-Only |
VendorName |
string |
- | The name of the vendor. |
VoucherNotes |
string |
- | Notes sent to Vendor along with authorization to charge Card Voucher. |
Vendor Banking Input/Response Schema
| Name | Type | Format | Description |
|---|---|---|---|
Items |
array |
VendorBank |
The result collection. |
NextPage |
string |
- | The URI of the next page of results, if any. |
RequestRunSummary |
string |
- | - |
TotalCount |
Int |
- | - |
VendorBank |
array |
VendorBank |
Required Vendor Banking Info |
VendorBank
| Name | Type | Format | Description |
|---|---|---|---|
AccountNumber |
string |
- | Required The account number. |
AccountType |
enum |
- | Required The account type--CHCK for Checking, SAVE for Savings. |
AddressCode |
string |
- | Required The Address Code. |
BankCode |
string |
- | Bank Code |
BankName |
string |
- | The bank name. |
BranchCode |
string |
- | Branch Code |
BranchLocation |
string |
- | The branch location |
CountryCode |
string |
- | The country code. |
CurrencyAlphaCode |
string |
- | The currency alpha Code. |
ID |
string |
- | The unique idenitifier of this resource. |
IsActive |
string |
- | Required Is information active |
NameOnAccount |
string |
- | Required The name on the account. |
RoutingNumber |
string |
- | The routing number. |
StatusList |
array |
status |
Status results |
TransType |
string |
- | The trans type. |
URI |
string |
- | The URI to the resource. |
VendorCode |
string |
- | Required The vendor code of the request. |
Vendor Group Input/Response Schema
| Name | Type | Format | Description |
|---|---|---|---|
Items |
array |
VendorGroup |
The result collection. |
NextPage |
string |
- | The URI of the next page of results, if any. |
RequestRunSummary |
string |
- | - |
TotalCount |
Int |
- | - |
VendorGroup |
array |
VendorGroup |
Required Vendor Group List |
VendorGroup
| Name | Type | Format | Description |
|---|---|---|---|
ID |
string |
- | The unique identifier of the resource. |
Name |
string |
- | Required The vendor group name. |
StatusList |
array |
status |
Status results. |
URI |
string | - | The URI to the resource. |
Status
| Name | Type | Format | Description |
|---|---|---|---|
Code |
int |
- | Code of request result |
Message |
string |
- | Message of request result |
RecordNumber |
int |
- | Record Number for create/update request. |
Type |
string |
- | Type request result |
Invoice Pay v4
- Overview
- Process Flow
- Products and Editions
- Scope Usage
- Dependencies
- Access Token Usage
- Obtaining Payments
- Updating a Payment With Status
- Schema
- Definitions
Overview
SAP Concur partners with external payment providers for processing invoice payments. These payment providers are listed on the App Center and can integrate with the Invoice product by using the Invoice Pay APIs. Payment providers can get a list of all the payments authorized to be processed by them, and send back status of those payments.
Limitations: This API is only available for use by payment partners who will be processing invoice payments. This API can accept a maximum of 10,000 requests per minute across all payment providers. This API is available only in the North America Data Center.
Process Flow

Products and Editions
- Concur Invoice Professional Edition
- Concur Invoice Standard Edition
Scope Usage
| Name | Description | Endpoint |
|---|---|---|
invoice.providerpayment.write |
Read access to pending payments, and write access to payment status | GET,POST |
Dependencies
This API can only be used with SAP Concur clients who have purchased Concur Invoice.
Access Token Usage
This API supports only Company access tokens.
Obtaining payments
Payment providers can use this endpoint to get a list of payments.
* This method will return all payments with a status PENDING_RETRIEVAL and payment method PAVPVD. After an invoice is approved and extracted it will be converted into a payment with status PENDING_RETRIEVAL.
* It returns a maximum of 500 records at a time. In order to ensure that all payments are retrieved, call this method until you receive an empty payment in the response.
* The payment provider will need to acknowledge that payments were received, using Updating a Payment With Status and updating the status of the payment to any status other than PENDING_RETRIEVAL.
Request
URI
Template
GET https://us.api.concursolutions.com/invoice/provider-payment/v4/payments
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
invoiceId |
string |
- | Optional: Gets specific payment info along with erpDocumentNumber. |
Headers
Payload
None.
Response
Status Codes
Headers
- RFC 7231 Content-Type
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
Payload
Example
Request
GET https://us.api.concursolutions.com/invoice/provider-payment/v4/payments
Accept: application/json
Authorization: BEARER {token}
Response
200 OK
Content-Type: application/json
{
"payments": [
{
"paymentId": "0f27533f-ce38-4f43-a2f3-fa9f0e6b33fc",
"paymentMethod": "PAYPVD",
"paymentDueDate": "2018-08-09",
"totalAmount":{
"amount": "30.00",
"currency": "USD"
},
"invoices": [
{
"invoiceNumber": "AGH87",
"invoiceID": "1ADFBB440D7045F68DE2",
"invoiceAmount":{
"amount": "30.00",
"currency": "USD"
},
"paymentAmount":{
"amount": "30.00",
"currency": "USD"
},
"notesToSupplier": null,
"erpDocumentNumber": "erp1234"
}
],
"vendor":{
"addressLine1": "1234 Rain Street",
"addressLine2": null,
"addressLine3": null,
"vendorAddrCode": "1160",
"city": "Chicago",
"state": "IL",
"postalCode": "60680-28160",
"countryName": "UNITED STATES",
"countryCode": "US",
"firstName": "Terry",
"lastName": "Brown",
"phoneNumber": null,
"email": "terry.brown@example.com",
"vendorCode": "1160",
"vendorName": "Dell",
"buyerAccountNumber": "1234567890"
}
}
]
}
Updating a Payment With Status
Payment providers can use this endpoint to provide updates to the status of payments.
Request
URI
Template
POST https://us.api.concursolutions.com/invoice/provider-payment/v4/payments/{paymentId}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
paymentId |
string |
- | Required The identifier of the payment to update. |
Headers
Payload
Response
Status Codes
Headers
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7231 Content-Type
Payload
Example
Request
POST https://us.api.concursolutions.com/invoice/provider-payment/v4/payments/0f27533f-ce38-4f43-a2f3-fa9f0e6b33fc
Authorization: BEARER {token}
Content-Type: application/json
{
"providerReference" : "hdoesofdl",
"status" : "PAID",
"statusMessage" : "Payment was successful",
"paymentAdjustmentNotes" : null,
"statusDate" : "2018-05-10",
"paymentInitiationDate" : "2018-05-09",
"paymentSettlementDate" : "2018-05-09",
"thirdPartyPaymentIdentifier" : "69249",
"paymentMethod" : "CHECK",
"paidAmount" : {
"amount": "30.00",
"currency": "USD"
}
}
Response
200 OK
Content-Type: application/json
{
"createdDate" : "2018-05-09",
"lastModifiedDate" : "2018-05-09",
"status" : "PAID",
"statusMessage" : "Payment was successful",
"paymentAdjustmentNotes" : null,
"statusDate" : "2018-05-10",
"paymentInitiationDate" : "2018-05-09",
"paymentSettlementDate" : "2018-05-09",
"thirdPartyPaymentIdentifier" : "69249",
"paymentMethod" : "CHECK",
"paidAmount" : {
"amount": "30.00",
"currency": "USD"
}
}
Schema
Payments
| Name | Type | Format | Description |
|---|---|---|---|
payments |
array |
Payment | Array of payments. |
Payment
| Name | Type | Format | Description |
|---|---|---|---|
invoices |
array |
Invoice | Array of invoices that need to be batched in a payment. |
paymentDueDate |
string |
YYYY-MM-DD | The date by which the payment should be made. |
paymentID |
string |
- | Unique identifier of the payment in SAP Concur. Maximum 36 characters. |
paymentMethod |
string |
- | The value is always PAYPVD which means that the client wants to pay using a payment provider. Maximum 15 characters. |
totalAmount |
object |
Amount | This amount needs to be paid to the vendor. |
vendor |
object |
Vendor | Vendor requesting the payment. |
Invoice
| Name | Type | Format | Description |
|---|---|---|---|
invoiceAmount |
object |
Amount | Amount on the invoice. |
invoiceNumber |
string |
- | Invoice Number. Maximum 50 characters. |
invoiceId |
string |
- | Unique identifier of the invoice in SAP Concur. This can be used to get additional invoice information from other APIs. This is the same as paymentRequestID in other Invoice APIs. Maximum 20 characters. |
notesToSupplier |
string |
- | Notes to the supplier contain remittance information that the buyer wants to provide to the supplier. Maximum 500 characters. |
paymentAmount |
object |
Amount | Payment amount on the invoice. |
erpDocumentNumber |
string |
- | ErpDocumentNumber of that invoice. |
Vendor
| Name | Type | Format | Description |
|---|---|---|---|
buyerAccountNumber |
string |
- | Buyer Account Number. Maximum 50 characters. |
vendorCode |
string |
- | Vendor Code. Maximum 32 characters. |
vendorName |
string |
- | Vendor Name. Maximum 255 characters. |
addressLine1 |
string |
- | Vendor Address line 1. Maximum 255 characters. |
addressLine2 |
string |
- | Vendor Address line 2. Maximum 255 characters. |
addressLine3 |
string |
- | Vendor Address line 3. Maximum 255 characters. |
city |
string |
- | Vendor Address City. Maximum 255 characters. |
state |
string |
- | Vendor Address State. Maximum 10 characters. |
countryCode |
string |
- | Vendor Address Country Code. Maximum 2 characters. |
countryName |
string |
- | Vendor Address Country Name. Maximum 64 characters. |
postalCode |
string |
- | Vendor Address Postal Code. Maximum 20 characters. |
vendorAddrCode |
string |
- | Vendor Address Code. Maximum 64 characters. |
email |
string |
- | Email Address. Maximum 255 characters. |
firstName |
string |
- | First Name. Maximum 255 characters. |
lastName |
string |
- | Last Name. Maximum 255 characters. |
phoneNumber |
string |
- | Phone Number. Maximum 25 characters. |
Amount
| Name | Type | Format | Description |
|---|---|---|---|
amount |
string |
- | Amount. Maximum 20 characters. |
currency |
string |
- | Currency Code. Maximum 3 characters. |
Payment Update
| Name | Type | Format | Description |
|---|---|---|---|
providerReference |
string |
- | Unique identifier of the payment in the payment provider's system. This will be used for internal troubleshooting. Maximum 100 characters. |
status |
string |
Payment Update Status | Required Used to depict success, error or any other intermediate state, defined by SAP Concur. |
statusMessage |
string |
- | Payment provider description of the status. Providers can supply any message. Maximum 255 characters. |
paymentAdjustmentNotes |
string |
- | Payment adjustment notes sent by the payment provider. Maximum 255 characters. |
statusDate |
string |
YYYY-MM-DD | Required The date that the payment provider recorded this status change. |
paymentInitiationDate |
string |
YYYY-MM-DD | The date the payment was initiated. |
paymentSettlementDate |
string |
YYYY-MM-DD | The date the payment will be in the payees account. |
thirdPartyPaymentIdentifier |
string |
- | Check number if the payment was done via check or trace number for ACH payments. Maximum 255 characters. |
paymentMethod |
string |
Payment Provider Method | Required if the status is PAID, CHECK_PROCESSED, or CARD_SETTLED Payment method used by the payment provider. |
paidAmount |
object |
Amount | Required if the status is PAID, CHECK_PROCESSED, or CARD_SETTLED Amount paid by the payment provider. |
Payment Update Result
| Name | Type | Format | Description |
|---|---|---|---|
createdDate |
string |
YYYY-MM-DD | The date the payment was created. |
lastModifiedDate |
string |
YYYY-MM-DD | The date the payment was last modified. |
providerReference |
string |
- | Unique identifier of the payment in the payment provider's system. Maximum 100 characters. |
status |
string |
Payment Update Status | Required Used to depict success, error or any other intermediate state, defined by SAP Concur. |
statusMessage |
string |
- | Payment provider description of the status. Providers can supply any message. Maximum 255 characters. |
paymentAdjustmentNotes |
string |
- | Payment adjustment notes sent by the payment provider. Maximum 255 characters. |
statusDate |
string |
YYYY-MM-DD | Required The date that the payment provider recorded this status change. |
paymentInitiationDate |
string |
YYYY-MM-DD | The date the payment was initiated. |
paymentSettlementDate |
string |
YYYY-MM-DD | The date the payment will be in the payees account. |
thirdPartyPaymentIdentifier |
string |
- | Check number if the payment was done via check or trace number for ACH payments. Maximum 255 characters. |
paymentMethod |
string |
Payment Provider Method | Required if the status is PAID, CHECK_PROCESSED, or CARD_SETTLED Payment method used by the payment provider. |
paidAmount |
object |
Amount | Required if the status is PAID, CHECK_PROCESSED, or CARD_SETTLED Amount paid by the payment provider. |
Errors
| Name | Type | Format | Description |
|---|---|---|---|
errors |
array |
Error | An array of errors. |
Error
| Name | Type | Format | Description |
|---|---|---|---|
errorCode |
string |
- | Required Machine readable code associated with the error. |
errorMessage |
string |
- | Required Human readable message associated with the error. |
Definitions
Payment Update Status
| Value | Description | Status available in the Payment Confirmation Extract |
|---|---|---|
PENDING_RETRIEVAL |
Not yet retrieved by the payment provider | Not available |
RETRIEVED |
Retrieved by the payment provider | Not available |
PROCESSING |
Payment is being processed by the payment provider | Not available |
REJECTED |
Payment was rejected by the payment provider | Not available |
RETURNED |
Payment was returned by the bank | Not available |
CANCELED |
Payment was canceled | FAILED |
CHECK_PRINTED |
Check was printed | Not available |
CHECK_MAILED |
Check was mailed | Not available |
CHECK_PROCESSED |
Check was processed | PAID |
CHECK_VOIDED |
Check was voided | VOID |
PAID |
Payment was successfully made | PAID |
CARD_EMAIL_SENT |
Email with card information sent to vendor | Not available |
CARD_AUTHORIZED |
Card was authorized by the merchant | Not available |
CARD_SETTLED |
Card was settled by vendor | PAID |
Payment Provider Method
| Value | Description |
|---|---|
ACH |
ACH payment |
CHECK |
Check payment |
WIRE |
Wire payment |
CARD |
Virtual Card payment |
OTHER |
Any other payment method |
Purchase Request v4 - Endpoints
- Create a New Purchase Request
- Get Purchase Request Details
- Schema
- Error Codes When the HTTP Status Code is 4xx
Version
4.0
Create a New Purchase Request
Create a Purchase Request based on provided header and line item details. If the request is valid it creates a purchase request and returns back a unique identifier to get the purchase request details.
Scopes
purchaserequest.write - Refer to Scope Usage for full details.
Request
URI
Template
POST /purchaserequest/v4/purchaserequests
Parameters
None
Headers
- RFC 7231 Content-Type
- RFC 7235 Authorization - Bearer Token that identifies the caller. This is the Company or User access token.
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
Payload
Response
Status Codes
Headers
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7231 Content-Type
- RFC 7230 Content-Length
- RFC 7231 Date
- RFC 7231 Server
Payload
Example
Request
This is a sample set of fields. The fields and values your entity requires will vary based on your edition of Concur Invoice, and your forms and fields configuration. This example includes commonly used fields.
POST /purchaserequest/v4/purchaserequests
Authorization: Bearer {token}
Content-Type: application/json
{
"description" : "New office supplies",
"userLoginId" : "john.deo@concur",
"policyExternalId" : "po-external-id",
"currencyCode" : "USD",
"notesToSupplier" : "Office space request phase 1",
"comments" : "office supplies request",
"custom1" : "ADVT",
"shipToAddressCode" : "SHIP15139",
"billToAddressCode" : "MNSLP129",
"lineItems" : [
{
"purchaseType" : "SERVICES",
"vendorCode" :"VEN1",
"vendorAddressCode" : "ADDR1",
"description" : "monitor",
"quantity" : "20",
"unitPrice" : "154.4",
"expenseType" : "1250",
"receiptType" : "NONE",
"neededByDate": "2018-06-28",
"uomCode" : "DA",
"shipping" : "13.5",
"tax" : "11",
"supplierPartId" : "DAQT1",
"url" :[
"http://officesupplies.com/monitor"
],
"notesToVendor" : "Phase 1 request monitor",
"comments" : "Phase 1 request for new employees for monitor",
"custom2" : "LGVT1"
},
{
"purchaseType" : "GOODS",
"vendorCode" :"VEN1",
"vendorAddressCode" : "ADDR1",
"description" : "office chair",
"quantity" : "20",
"unitPrice" : "346.2",
"expenseType" : "1251",
"receiptType" : "QUANTITY_RECEIPT",
"neededByDate": "2018-06-28",
"uomCode" : "DA",
"shipping" : "15",
"tax" : "17.5",
"supplierPartId" : "DAQT2",
"url" :[
"http://officesupplies.com/officechair"
],
"notesToVendor" : "Phase 1 request office chair",
"comments" : "Phase 1 request for new employees for office chair",
"custom3" : "DEPT",
"custom4" : "SALES"
}
]
}
Response
HTTP/1.1 202 Accepted
Content-Type: application/json
Date: date-requested
Content-Length: 1000
concur-correlationid: 1234abcd-12ab-34cd-56ef-123456abcdef
{
"id" : "b1e22581-ff4a-48e9-981b-2f5065579096",
"uri": "http://us.api.concursolutions.com/purchaserequest/v4/purchaserequests/b1e22581-ff4a-48e9-981b-2f5065579096?mode=COMPACT"
}
Get Purchase Request Details
Gets purchase request details. The supported mode is COMPACT, which returns basic info about the purchase request along with any exceptions.
Scopes
purchaserequest.read - Refer to Scope Usage for full details.
Request
URI
Template
GET /purchaserequest/v4/purchaserequests/{id}?mode=COMPACT
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
mode |
string |
- | Required: Specifies mode for Get Purchase Request Details. Supported value: COMPACT |
Headers
- RFC 7231 Content-Type
- RFC 7235 Authorization - Bearer Token that identifies the caller. This is the Company or User access token.
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
Payload
None
Response
Status Codes
Headers
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7231 Content-Type
- RFC 7230 Content-Length
- RFC 7231 Date
- RFC 7231 Server
Payload
Example
Request
GET /purchaserequest/v4/purchaserequests/de9c0894-b807-6943-8e3f-49a707da3456?mode=COMPACT
Authorization: Bearer {token}
Content-Type: application/json
Response
HTTP/1.1 200 OK
Content-Type: application/json
Date: date-requested
Content-Length: 1000
concur-correlationid: 1234abcd-12ab-34cd-56ef-123456abcdef
{
"purchaseRequestId" : "de9c0894-b807-6943-8e3f-49a707da3456",
"purchaseRequestNumber" : "100000",
"purchaseRequestQueueStatus" : "CREATED",
"purchaseRequestWorkflowStatus" : "Approved",
"purchaseRequestExceptions": [
{
"message": "Line Item Quantity does not match",
"eventCode": "PURCH_DETAIL_ITEM_SAVE",
"exceptionCode": "0070071",
"isCleared": false,
"prExceptionId": "fe636831-43a1-9540-bf86-32e2c19400af"
}
],
"purchaseOrders": [
{
"purchaseOrderNumber": "PO10001"
}
]
}
Schema
Create Purchase Request Schema
| Name | Type | Format | Description |
|---|---|---|---|
userId |
string |
- | Required: The employee that is requesting the items. This is the UUID of the employee. Either UserId or UserEmail or UserLoginId is required to identify the employee. |
userEmail |
string |
- | Required: The employee that is requesting the items. This is the employee's email. Either UserId or UserEmail or UserLoginId is required to identify the employee. |
userLoginId |
string |
- | Required: The employee that is requesting the items. This is the employee's Login Id. Either UserId or UserEmail or UserLoginId is required to identify the employee. |
description |
string |
- | A description of the purchase request. |
policyExternalId |
string |
- | The external identifier of the policy that should be associated with the purchase request. If not supplied, the API will use the default policy set up for the user group assigned to the requesting employee. This is the External Id from the Invoice Policy configuration. Clients will need to get these Ids from their SAP Concur contact if they need to assign policies other than the group default. |
currencyCode |
string |
- | Required: The 3-letter ISO 4217 currency code of the currency that is associated with the purchase request. This code will be used for all items on this request. Example: USD |
notesToSupplier |
string |
- | Notes to print on the transmitted purchase order PDF sent to the supplier. |
comments |
string |
- | Internal comments related to this record. |
custom1 through custom24 |
string |
- | Each custom field used should have its own row in the message. If the field is tied to a connected list, the accepted value is the list Item Code configured for the list in SAP Concur. |
shipToAddressCode |
string |
- | The shipping address of the Purchase Request. The accepted value is the address code from ShipTo record. If not supplied, the API will use the requesting user's default shipping address. |
billToAddressCode |
string |
- | The billing address of the Purchase Request to be used for invoicing. The accepted value is the address code from the BillTo record. If not supplied the API will use the policy's default BillTo address. |
lineItems |
array |
LineItem |
Required: Requested items or services related to this Purchase Request. |
LineItem
| Name | Type | Format | Description |
|---|---|---|---|
purchaseType |
string |
- | Required: The type of item, either goods or services. Displayed as Type in Concur Invoice. Supported values: GOODS, SERVICES. |
vendorCode |
string |
- | Required: The code that identifies the vendor. This value can be found in the vendor information form of Vendor Manager. This is used along with Vendor Address Code to determine the specific Vendor record. |
vendorAddressCode |
string |
- | Required: The code that identifies the vendor's address. This value can be found in the vendor information form of Vendor Manager and is labeled Address Accounting Code. This is used along with Vendor Code to determine the specific Vendor record. |
description |
string |
- | Required: A description of the line item. |
quantity |
decimal |
- | Required: The quantity associated with the line item. |
unitPrice |
decimal |
- | Required: The unit price of the line item. |
expenseType |
string |
- | The PET code of the Expense Type that will be assigned to the line item. If not supplied it will default to the Expense Type set up on the Vendor Profile used for the item. Clients will need to get these PET codes from their SAP Concur contact. |
receiptType |
string |
- | The type of receipt. If not supplied, the API will use the purchaseType to set this field to NONE for SERVICES, or QUANTITY_RECEIPT for GOODS. If you are using SAP Concur Receiving and need to enter Goods Receipts against the resulting PO lines use QUANTITY_RECEIPT. Supported values: QUANTITY_RECEIPT, NONE. |
neededByDate |
date |
YYYY-MM-DD | The date by which the purchase order must be fulfilled. Example: 2018-03-23 |
uoMCode |
string |
- | Unit of Measure (UOM) code for the purchase request item. Accepted values are the UOM Codes set up in the Unit of Measure configuration in Concur Invoice. If not supplied, the API will default a UOM based on the defaults for goods and services. |
shipping |
decimal |
- | The total shipping cost for the item. |
tax |
decimal |
- | Tax amount that is associated with the line item. |
supplierPartId |
string |
- | An Id value that helps to identify the line item. This could be a value such as the vendor’s part number or the manufacturer number. |
url |
array |
- | A URL related to the item. You can have multiple URLs per item, enclosed in quotes and comma separated. |
notesToVendor |
string |
- | Notes related to the item that display on the transmitted purchase order PDF to the vendor. |
comments |
string |
- | Internal comments related to this record. |
custom1 through custom20 |
string |
- | Each custom field used should have its own row in the message. If the field is tied to a connected list, the accepted value is the List Item Code configured for the list in SAP Concur. |
Create Purchase Request Response Schema
| Name | Type | Format | Description |
|---|---|---|---|
errors |
array |
Error |
An array of errors indicating which fields have failed validation. |
id |
string |
- | The unique purchase request reference ID if the request has passed all validations. This reference ID will be needed to look up details of the purchase request. |
uri |
string |
- | The URI to look up details of the newly created purchase request. |
Get Purchase Request Response Schema
| Name | Type | Format | Description |
|---|---|---|---|
purchaseRequestId |
string |
- | The unique purchase request reference Id. Returned by the Create Purchase Request API call. |
purchaseRequestNumber |
string |
- | The unique purchase request identifier which can be used to uniquely identify a purchase request in SAP Concur products. |
purchaseRequestQueueStatus |
string |
- | The creation status of the purchase request. Possible values are: PENDING_CREATION, CREATED, CREATE_FAILED. |
purchaseRequestWorkflowStatus |
string |
- | The workflow status of the purchase request. Possible values are: Approved, Pending Approval, Pending Cost Object Approval, Sent Back To Employee, Not Submitted, Submitted, Pending Processor Review, Vendor Approval, Approval Time Expired. |
purchaseOrders |
array |
PurchaseOrders |
If the purchase request has been approved and a purchase order generated, this array contains the purchase order details. If empty, this element will not be returned. |
purchaseRequestExceptions |
array |
PurchaseRequestExceptions |
An array of exceptions, if present on the purchase request. If empty, this element will not be returned. |
PurchaseOrders
| Name | Type | Format | Description |
|---|---|---|---|
purchaseOrderNumber |
string |
- | The purchase order number. |
PurchaseRequestExceptions
| Name | Type | Format | Description |
|---|---|---|---|
eventCode |
string |
- | The event code of the exception. Example: PURCH_DETAIL_SUBMIT |
exceptionCode |
string |
- | The unique exception code. |
isCleared |
boolean |
- | Whether the exception has been cleared. |
prExceptionId |
string |
- | The unique exception id of the purchase request. |
message |
string |
- | The message of the exception with details. |
Error
| Name | Type | Format | Description |
|---|---|---|---|
errorCode |
string |
- | An error code indicating why a field failed validation. |
errorMessage |
string |
- | A description of the error. |
dataPath |
string |
- | The path to the request data which has the error message. |
Error Codes When the HTTP Status Code is 4xx
| ErrorCode | Error Message |
|---|---|
| missingRequestBody | Missing request body. |
| invalidRequestBody | Passed request body is invalid. |
| missingUserInfo | Either userID or userEmail or userLoginId is required. |
| invalidUserInfo | Either userID or userEmail or userLoginId is invalid, or user does not have access to this resource. |
| provideOneUserInformation | Either userID or userEmail or userLoginId is required. |
| missingCurrencyCode | currencyCode is missing. |
| invalidCurrencyCode | currencyCode is invalid. |
| invalidPolicyInformation | Cannot find a purchase order policy with the supplied policyExternalId. |
| missingLineItems | lineItems are missing. |
| invalidPurchaseType | purchaseType is invalid. |
| missingPurchaseType | purchaseType is required. |
| missingVendorAddressCode | vendorAddressCode is required. |
| missingVendorCode | vendorCode is required. |
| invalidVendor | Vendor / Address code combination is invalid. |
| missingDescription | Line item description is required. |
| missingQuantity | Line item quantity is required. |
| invalidQuantity | Line item quantity is invalid. |
| missingUnitPrice | unitPrice is required. |
| invalidUnitPrice | unitPrice is invalid. |
| invalidDateFormat | Expected a date in the format YYYY-MM-DD. |
Purchase Request v4 - Get Started
The Purchase Request API gives SAP Concur clients the ability to leverage external data to create purchase requests for pre-authorization of purchase orders. Clients can build a direct connection to the Purchase Request API which will create new purchase requests and automatically submit them into the pre-authorization workflow. Once approved, the purchase request results in a purchase order that can be transmitted to a vendor from SAP Concur.
Use Case
Many Concur Invoice clients have external systems that have part or service lists with pricing. If they use SAP Concur pre-authorization using purchase request, the data from the external systems must be entered manually into the purchase request cart and submitted for approval by the requesting employee. Using this API and a client-built integration, the requestor can browse and select the items from the external system with quantities and other details needed, and then send the data to SAP Concur. A purchase request will be created and submitted into the workflow. The API returns a response message with a record identifier (URI), which can be used with the Get Purchase Request Details method to get the basic details of the created purchase request: Concur Purchase Request number, workflow status, exceptions, and once approved, the resulting SAP Concur purchase order number.
Limitations
This API is not available in the China Data center. This API is only available for direct integrations with an existing SAP Concur client. If you are a Partner looking to build an App Center App using this API, please reach out to your SAP Concur Representative. This API can only be used to create new purchase requests and get the details of the created purchase request. This API cannot update, edit, or delete purchase requests. All edits or processing of the purchase request after it is sent to SAP Concur and created must be done in SAP Concur.
- Regional Availability
- Products and Editions
- Scope Usage
- Dependencies
- Access Token Usage
- Purchase Request API Endpoints
Regional Availability
https://us.api.concursolutions.com/purchaserequest/v4/
https://emea.api.concursolutions.com/purchaserequest/v4/
Products and Editions
- Concur Invoice Professional Edition
- Concur Invoice Standard Edition
Scope Usage
| Name | Description | Endpoint |
|---|---|---|
| purchaserequest.write | Allows you to create new purchase requests | POST |
| purchaserequest.read | Allows you to retrieve purchase requests | GET |
Dependencies
SAP Concur clients must purchase Concur Invoice, Concur Purchasing, and Concur Web Services in order to use this API. Concur Invoice with Concur Purchasing must be configured before using this API.
To create purchase requests, you need to supply a Vendor Code and Vendor Address Code. You can access Vendor Manager in Concur Invoice to see these values. If you need to get this data from SAP Concur using web services, you can use the Vendor v3 API.
If your purchase request form in SAP Concur has required custom fields that are tied to lists, you will need to supply the Item Code for the list items, or configure them to copy down from another source such as Employee. You can access List Management in SAP Concur to see your list items and list item codes. If you need to get this data from SAP Concur using web services, you can use the List Item v3 API to retrieve the Level1Code value for the list items.
Access Token Usage
This API will work with both Company or User access tokens, however a Company access token is required if the integration will create purchase requests for multiple requestors. Using a User access token to create purchase requests results in the purchase request being assigned to the user that generated the User access token, not the user set in the payload. A User access token can be used for testing purposes.
Retrieve a Company Access Token
Clients connecting to this API to build a custom integration will receive client credentials and information on how to generate your Company access token or Company refresh token from your Concur Technical Enablement resource.
Retrieve a User Access Token
This API supports User access tokens, however any purchase requests created using a User access token will only create/assign these requests to the user that generated the User access token. Before making requests to the Purchase Request API, you must obtain an access token from the Authentication API.
The response will include an access_token field, which contains your access token. For subsequent calls, you will need to include this access token in the Authorization header of your calls. An id_token will be also included in the response. In order to retrieve the unique ID for your user, you will have to decode this id_token at jwt.io. You will need this ID in order to post Purchase Requests.
LOCATE
User Locations v4
Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.
Overview
The goal of this API is to allow customers and third party vendors to add their traveler's location data to Concur Locate so it can be utilized locate and contact travelers to address their duty of care requirements.
This API supports POST only.
Limitations: This API is available only in the North America and EMEA Data Centers.
Products and Editions
- Concur Expense Professional Edition
- Concur Expense Standard Edition
- Concur Travel Professional Edition
- Concur Travel Standard Edition
Scope Usage
Required Scopes:
| Name | Description | Endpoint |
|---|---|---|
locate.location.read |
Get user location information. | POST |
locate.location.write |
Post user location information. | POST |
Dependencies
None.
Access Token Usage
This API supports company level access tokens.
POST Endpoint
The service is a POST call adhering to the following steps:
- Vendor onboarding has been completed prior to invoking the API. All the authentication and authorization credentials have been set up at this point.
- Third party vendors invoke the User Location API using the client credentials (JWT)
- Since the new service is registered with API gateway, the call is intercepted by the API Gateway and basic authentication and authorization for the given client credentials (JWT) is done
- If the checks fail, then the appropriate error response is returned to the caller.
- If the checks pass, then the request is forwarded to the load balancer which routes the request to the appropriate node for processing
- The selected node processes the request which is in JSON format. Validations are performed the data conversion takes place. If any of the validations fail, then the appropriate error response is returned to the client (HTTP 400 Bad Request / HTTP 403 Unauthorized)
- If the validations pass, then the request is processed, and the data is persisted to the backend (DB) in the following ways:
- Direct persistence
- Persistence via queues
- If the persistence is successful, then an HTTP 200 OK is returned to the caller
- If there are any issues with the persistence, then the appropriate codes are returned to the caller (HTTP 500 Application exception)
- Note that the error messages are intentionally ambiguous to prevent exploitation
Request
URI
Template
POST https://us.api.concursolutions.com//locate/api/v4/user/locations
Headers
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7230 Host
- RFC 7231 Accept
- RFC 7231 Accept-Encoding
- RFC 7231 Accept-Language
- RFC 7235 Authorization
- RFC 7231 Referer
- RFC 7231 User-Agent
Payload
-
Response
Status Codes
Headers
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7231 Content-Encoding
- RFC 7231 Content-Type
- RFC 7231 Date
- RFC 7230 Transfer-Encoding
- RFC 7231 Vary
Payload
-
Example
Mobile and Mobile Country Code Valid Combinations
Example with country code for South Africa (country Code: ZA)
| Country Code | Mobile Number |
|---|---|
| Empty | 7160986233 |
| JP | 800122334 |
| 81 | 800122334 |
- When
mobileCountryCodeis non-blank it will validate the mobile number against that country’s market. It will accept the country letters (in this case JP) or the country code (in this case 81) - When
mobileCountryCodeis blank, it will default to the client country (client id defined in the client section of the JSON) - Mobile is validated against the
mobileCountryCodeor default country (as mentioned in point 1 above) if this field is blank. When a mobile number is provided there are no issues as long as it follows the appropriate format and is a valid mobile in the country where it is registered. For e.g If themobileCountryCodeprovided in the JSON is 81 (JP - Japan) then the subsequent mobile number must be valid in JP. - If the
mobileCountryCodeis not provided in the JSON and the client country is US then the mobile number provided must be valid in US because of the default behaviour mentioned above. mobileCountryCodecan be of the following two variants- A 2-letter ISO code (e.g US, JP, IT)
- A 4 digit International Calling Code.
Please ensure that there are no special characters and spaces in the
mobileormobileCountryCodefields. Also ensure that the above limits and datatypes are strictly followed to prevent unwanted behaviour of the system.
A new field partiallyProcessedTransactions is introduced in the response to cater to the following invalid mobile scenarios.
* Mobile number is not valid for the country derived based on details provided for traveller
* A well formed mobile number could not be derived using the mobile provided
Request
Cancel request without location and user fields (minimal request)
POST https://{baseURI}/locate/api/v4/user/locations
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}
{
"userLocations": [
{
"client": {
"id": "UL_CLI"
},
"sourcePartner": {
"id": "SP",
"name": "Source Partner",
"description": "Source Partner"
},
"transaction": {
"transactionId": "AAAAAA",
"createdDate": "2018-08-06T12:05",
"transactionType": "Cancel"
}
}
]
}
Response
200 OK
date: Mon, 15 May 2018 14:28:07 GMT
content-length: 20
content-type: application/json
{
"processedTransactions": {
"AAAAAA" : "Successfully Processed"
},
"unprocessedTransactions": {
},
"partiallyProcessedTransactions": {
}
}
Request
Add request
POST https://{baseURI}/locate/api/v4/user/locations
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}
{
"userLocations": [
{
"client": {
"id": "UL_CLI",
"firstSubLevel": "",
"secondSubLevel": ""
},
"users": [
{
"visitorId": 22,
"firstName": "Test",
"lastName": "TEST3",
"email": "test.test3@abcd.com",
"employeeId": "abc333",
"mobileCountryCode": "27",
"mobile": "7160981138",
"optedIn": true,
"concurLoginId": "",
"affiliation": "Student"
},
{
"visitorId": 23,
"firstName": "Test",
"lastName": "TEST4",
"email": "test.test4@abcd.com",
"employeeId": "abc334",
"mobileCountryCode": "US",
"mobile": "2125551138",
"optedIn": true,
"concurLoginId": "",
"affiliation": "Student"
}
],
"locations": [
{
"locationId": 0,
"locationAddress": "",
"locationName": "SomeLocation",
"locationDescription": "",
"locationLatitude": "",
"locationLongitude": "",
"locationIataCode": "LHR",
"startDate": "2018-09-01T12:07",
"endDate": "2018-09-02T12:07",
"timezoneId": "Europe/London",
"locationPhone": "",
"visitorId": [
22,23
]
}
],
"sourcePartner": {
"id": "SP",
"name": "Source Partner",
"description": "Source Partner"
},
"transaction": {
"transactionId": "ASDFGH",
"createdDate": "2018-08-06T12:05",
"transactionType": "Add"
}
}
]
}
Response
200 OK
date: Mon, 15 May 2018 14:28:07 GMT
content-length: 20
content-type: application/json
{
"processedTransactions": {
"ASDFGH" : "Successfully Processed"
},
"unprocessedTransactions": {
},
"partiallyProcessedTransactions": {
}
}
Request
Add request - mobile phone variation
POST https://{baseURI}/locate/api/v4/user/locations
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}
{
"userLocations": [
{
"client": {
"id": "UL_CLI",
"firstSubLevel": "",
"secondSubLevel": ""
},
"users": [
{
"visitorId": 22,
"firstName": "Test",
"lastName": "TEST3",
"email": "test.test3@abcd.com",
"employeeId": "abc333",
"mobileCountryCode": "",
"mobile": "+(27)7160981138",
"optedIn": true,
"concurLoginId": "",
"affiliation": "Student"
},
{
"visitorId": 23,
"firstName": "Test",
"lastName": "TEST4",
"email": "test.test4@abcd.com",
"employeeId": "abc334",
"mobileCountryCode": "US",
"mobile": "2125551138",
"optedIn": true,
"concurLoginId": "",
"affiliation": "Student"
}
],
"locations": [
{
"locationId": 0,
"locationAddress": "",
"locationName": "SomeLocation",
"locationDescription": "",
"locationLatitude": "",
"locationLongitude": "",
"locationIataCode": "LHR",
"startDate": "2018-09-01T12:07",
"endDate": "2018-09-02T12:07",
"timezoneId": "Europe/London",
"locationPhone": "",
"visitorId": [
22,23
]
}
],
"sourcePartner": {
"id": "SP",
"name": "Source Partner",
"description": "Source Partner"
},
"transaction": {
"transactionId": "ASDFGH",
"createdDate": "2018-08-06T12:05",
"transactionType": "Add"
}
}
]
}
Response
200 OK
date: Mon, 15 May 2018 14:28:07 GMT
content-length: 20
content-type: application/json
{
"processedTransactions": {
"ASDFGH" : "Successfully Processed"
},
"unprocessedTransactions": {
},
"partiallyProcessedTransactions": {
}
}
Request
Add request - invalid mobile phone variation
POST https://{baseURI}/locate/api/v4/user/locations
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}
{
"userLocations": [
{
"client": {
"id": "UL_CLI",
"firstSubLevel": "",
"secondSubLevel": ""
},
"users": [
{
"visitorId": 22,
"firstName": "Test",
"lastName": "TEST3",
"email": "test.test3@abcd.com",
"employeeId": "abc333",
"mobileCountryCode": "",
"mobile": "+(27)7160981138",
"optedIn": true,
"concurLoginId": "",
"affiliation": "Student"
},
{
"visitorId": 23,
"firstName": "Test",
"lastName": "TEST4",
"email": "test.test4@abcd.com",
"employeeId": "abc334",
"mobileCountryCode": "US",
"mobile": "0005551138",
"optedIn": true,
"concurLoginId": "",
"affiliation": "Student"
}
],
"locations": [
{
"locationId": 0,
"locationAddress": "",
"locationName": "SomeLocation",
"locationDescription": "",
"locationLatitude": "",
"locationLongitude": "",
"locationIataCode": "LHR",
"startDate": "2018-09-01T12:07",
"endDate": "2018-09-02T12:07",
"timezoneId": "Europe/London",
"locationPhone": "",
"visitorId": [
22,23
]
}
],
"sourcePartner": {
"id": "SP",
"name": "Source Partner",
"description": "Source Partner"
},
"transaction": {
"transactionId": "ASDFGH",
"createdDate": "2018-08-06T12:05",
"transactionType": "Add"
}
}
]
}
Response
200 OK
date: Mon, 15 May 2018 14:28:07 GMT
content-length: 20
content-type: application/json
{
"processedTransactions": {
},
"unprocessedTransactions": {
},
"partiallyProcessedTransactions": {
"ASDFGH": "Partially processed the transactions : [Incorrect mobile for [23] ]"
}
}
Request
Add request - unprocessed transaction
POST https://{baseURI}/locate/api/v4/user/locations
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}
{
"userLocations": [
{
"client": {
"id": "UL_CLI",
"firstSubLevel": "",
"secondSubLevel": ""
},
"users": [
{
"visitorId": 22,
"firstName": "Test",
"lastName": "TEST3",
"email": "test.test3@abcd.com",
"employeeId": "abc333",
"mobileCountryCode": "",
"mobile": "+(27)7160981138",
"optedIn": true,
"concurLoginId": "",
"affiliation": "Student"
},
{
"visitorId": 23,
"firstName": "Test",
"lastName": "TEST4",
"email": "test.test4@abcd.com",
"employeeId": "abc334",
"mobileCountryCode": "US",
"mobile": "asdfrgh",
"optedIn": true,
"concurLoginId": "",
"affiliation": "Student"
}
],
"locations": [
{
"locationId": 0,
"locationAddress": "",
"locationName": "SomeLocation",
"locationDescription": "",
"locationLatitude": "",
"locationLongitude": "",
"locationIataCode": "LHR",
"startDate": "2018-09-01T12:07",
"endDate": "2018-09-02T12:07",
"timezoneId": "Europe/London",
"locationPhone": "",
"visitorId": [
22,23
]
}
],
"sourcePartner": {
"id": "SP",
"name": "Source Partner",
"description": "Source Partner"
},
"transaction": {
"transactionId": "ASDFGH",
"createdDate": "2018-08-06T12:05",
"transactionType": "Add"
}
}
]
}
Response
200 OK
date: Mon, 15 May 2018 14:28:07 GMT
content-length: 20
content-type: application/json
{
"processedTransactions": {
},
"unprocessedTransactions": {
"ASDFGH": "Invalid mobile details found for transaction [ASDFGH]. Skipping transaction "
},
"partiallyProcessedTransactions": {
}
}
Schema
| Name | Type | Format | Description |
|---|---|---|---|
UserLocations |
object |
UserLocations |
Required Contains the Client, Users, Locations, SourcePartner and Transaction. |
Client |
object |
Client |
Required This indicates which entity within the organization the traveler belongs to. |
Users |
object |
Users |
Required This is the users' information. This will be used to either create a new traveler or to match with an existing traveler. |
Locations |
object |
Locations |
Required This is the users' location information. Multiple locations can be passed for a single user. |
SourcePartner |
object |
SourcePartner |
Required This is used to identify your application. This information will be provided to you in advance. |
Transaction |
object |
Transaction |
Required Whether this transaction adds or cancels itineraries/locations. |
Client
This indicates which entity within the organization the traveler belongs to. This will vary by client. You will be provided with a list of the applicable agencies for each customer.
| Name | Type | Format | Description |
|---|---|---|---|
Id |
string |
- | Required This maps to the top level corporation. Maximum length: 36 |
firstSubLevel |
string |
- | This is the child corporation i.e one level below the top level corporation. Maximum length: 36 |
secondSubLevel |
string |
- | This is the sub level of the child corporation (firstsublevel). Maximum length: 36 |
Users
This information will be used to match or create a new user. Either login ID or email address must be provided. If an existing user is not found for the login ID or email, one will be created.
| Name | Type | Format | Description |
|---|---|---|---|
visitorId |
long |
- | Required This is a unique identifier for the user generated by your application. Maximum length: 10 |
firstName |
string |
- | Required The first name of the user. Maximum length: 100 |
lastName |
string |
- | Required The last name of the user. Maximum length: 100 |
email |
string |
- | Either email or concurLoginId must be provided Maximum length: 255 |
employeeId |
string |
- | Optional field to indicate the employee ID of the user. Maximum length: 19 |
mobileCountryCode |
string |
- | Either ISO Alpha-2 code or International Calling Codes (4 digits). Maximum length: 4 |
mobile |
string |
- | The contact number of the user. Maximum length: 10 |
optedIn |
boolean |
- | If true, indicates if the user has chosen to receive messages via SMS or text. |
concurLoginId |
string |
- | Either email or concurLoginId must be provided |
affiliation |
string |
- | Used to indicate the type of traveler (e.g. employee, student, faculty). Maximum length: 128 |
Locations
This section includes information about the traveler's future or current location. Either the location latitude and longitude or the IATA (airport) code must be present. If both are present, the latitude and longitude take precedence.
| Name | Type | Format | Description |
|---|---|---|---|
locationId |
string |
- | Identifier of the travel location. |
locationAddress |
string |
- | Address of the travel location. Maximum length: 512 |
locationName |
string |
- | Name of the travel location. Maximum length: 100 |
locationDescription |
string |
- | A short description of the travel location. Maximum length: 100 |
locationPhone |
string |
- | Contact details of the travel location. Maximum length: 50 |
locationLatitude |
string |
- | Either locationIATACode or locationLatitude/locationLongitude must be provided |
locationLongitude |
string |
- | Either locationIATACode or locationLatitude/locationLongitude must be provided |
locationIATACode |
string |
- | Either locationIATACode or locationLatitude/locationLongitude must be provided The three character IATA airport code. Maximum length: 3 |
startDate |
string |
YYYY-MM-DDTHH:MM |
Required Traveler's arrival date. Maximum length: 16 |
endDate |
string |
YYYY-MM-DDTHH:MM |
Required Traveler's departure date. Maximum length: 16 |
timezoneId |
string |
- | Required Maximum length: 60 |
visitorID |
string |
- | This corresponds to the visitorId provided in the Users schema. IDs present in this array must be present in the Users schema. Maximum length: 10 |
Source Partner
This information will be provided to you along with your client ID and secret.
| Name | Type | Format | Description |
|---|---|---|---|
Id |
string |
- | Required This will provide to clients similar to the Client ID. Maximum length: 2 |
name |
string |
- | The name of the source provider. Example: Source Provider1. Maximum length: 100 |
description |
string |
- | A short description of the source provider. Maximum length: 100 |
Transaction
Itineraries can be added or cancelled. This section allows you to indicate whether this is an addition of a new itinerary or cancellation of an existing itinerary. A cancellation request is for canceling the itinerary completely in our system and if there are any updates to the existing itineraries then it needs to be resent using the same booking or transaction ID.
| Name | Type | Format | Description |
|---|---|---|---|
transactionId |
string |
- | Required This is a unique identifier generated by your application for the request. Maximum length: 5 |
createdDate |
string |
YYYY-MM-DDTHH:MM |
Required Maximum length: 16 |
transactionType |
string |
- | Required Add is indicative of creating a new itinerary or updating an existing itinerary. Cancel means removing the itinerary. Cancel works only on future dated itineraries. Supported values: Add, Cancel |
NOTIFICATIONS
Partner Notifications v4
The purpose of this API is to provide SAP Concur partners the ability to message users through the web and mobile product.
Sample use case: A business traveller starts a travel booking. That user is notified that a visa is required for their trip.
- Process Flow
- Products and Editions
- Scope Usage
- Dependencies
- Access Token Usage
- Send a message
- Schema
Process Flow

Products and Editions
- Concur Travel Professional Edition
- Concur Travel Standard Edition
Scope Usage
| Name | Description | Endpoint |
|---|---|---|
notifications.messages.writeonly |
Write messages to the notifications platform | POST |
Dependencies
- User Profile Service - Get user information using access token (JWT)
- Events Service - Use access token (JWT) and
sessionIdto call the Partner Notifications API
Access Token Usage
A Company access token (JWT) is required for this endpoint.
Send a message
The endpoint provides a way for SAP Concur partners to message users and notify them. Partners will provide the identifier of the pre-configured message template, along with the data to apply to the message.
Scopes
notifications.messages.writeonly - Refer to Scope Usage for full details.
Request
URI
Template
https://us.api.concursolutions.com/notifications/v4/messages/{userId}/session
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
userId |
string |
- | Required The userId of the user to whom the notification should be sent. |
Headers
Payload
Response
Status Codes
- 200 OK
- 400 Bad Request
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found
- 500 Internal Server Error
- 503 Service Unavailable
- 504 Gateway Timeout
Headers
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace.- RFC 7231 Content-Type
- RFC 7231 Content-Encoding
- RFC 7230 Content-Length
- RFC 7231 Content-Type
Payload
- HTTP Headers Only
- Error
Example
Request
POST https://us.api.concursolutions.com/notifications/v4/messages/0E6BD8D8-A020-43C6-BBEC-B67A7021FF1C
/session
Accept: application/json
Authorization: Bearer {JWT}
content-type: application/json
{
"sessionId": "D5B80C53-A4D2-4949-8462-D41655F246E2",
"templateId": "template-name",
"context": {
"url": "https://www.example.com/foo"
}
}
Response
HTTP/1.1 200 OK
concur-correlationid: 848618e7-5747-4970-bda7-fc7baf251f88
Content-Type: application/json; charset=utf-8
Date: Thu, 24 Jan 2019 01:31:47 GMT
Schema
| Name | Type | Format | Description |
|---|---|---|---|
sessionId |
string |
- | Required The unique ID of the session |
templateId |
string |
- | Required The template identifier of the message |
context |
object |
context | Contains additional information required for the template |
Context
| Name | Type | Format | Description |
|---|---|---|---|
url |
string |
- | The context URL to apply to the template. Please contact SAP Concur to add domains to the approved list. |
Error
| Name | Type | Format | Description |
|---|---|---|---|
errorId |
string |
- | The unique ID of the error |
errorCode |
string |
- | The error code |
errorMessage |
string |
- | A message describing the error |
errors |
array |
error |
An array of errors. Note: this points to this schema as errors can nest. |
PROFILE
Identity v4
- Overview
- Products and Editions
- Scope Usage
- Dependencies
- Access Token Usage
- Retrieve Users
- Retrieve a User's Identity Profile
- Create a User's Identity Profile
- Update a User's Identity Profile
- Replace a User's Identity Profile
- Schema
Overview
The Identity v4 service is designed to create, update, and read user’s core identity profile. This service is also available to look up the SAP Concur UUID to access any v4 API for a single user only.
This API is used to help provision and manage user accounts and profile details across multiple SAP Concur products, including Expense, Invoice, Request, Travel, and TripIt.
Limitations: Only the GET operations are available at this time. This API is not available in the China Data Center. This API is only available to partners who have been granted access by SAP Concur. Access to this documentation does not provide access to the API.
Products and Editions
- Concur Expense Professional Edition
- Concur Expense Standard Edition
- Concur Travel Professional Edition
- Concur Travel Standard Edition
- Concur Invoice Professional Edition
- Concur Invoice Standard Edition
- Concur Request Professional Edition
- Concur Request Standard Edition
Scope Usage
| Name | Description | Endpoint |
|---|---|---|
identity.user.ids.read |
Read user ID data. | GET |
identity.user.core.read |
Read user core data. | GET |
identity.user.coresensitive.read |
Read core sensitive data. | GET |
identity.user.enterprise.read |
Read user enterprise data. | GET |
identity.user.coreenterprise.writeonly |
Write access to all core and enterprise fields except externalID. |
PUT, POST, PATCH |
identity.user.externalID.writeonly |
Write access to externalID only. |
PUT, POST, PATCH |
For more information on scope usage and mapping, please see the Identity v4 Scope Mapping page.
Dependencies
None.
Access Token Usage
This API supports only company level access tokens.
Retrieve Users
Retrieves all users of a given company. The filter operation can be used to fetch a unique user’s identity information.
Request
URI
Template
GET https://us.api.concursolutions.com/profile/identity/v4/Users
GET https://us.api.concursolutions.com/profile/identity/v4/Users?count=20
GET https://us.api.concursolutions.com/profile/identity/v4/Users/<UUID>
GET https://us.api.concursolutions.com/profile/identity/v4/Users?filter=attributes eq "value"
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
filter |
string |
- | The filter string used to request a subset of resources. |
attributes |
object |
- | A multi-valued list of strings indicating the names of resource attributes to return in the response. It is comma delimited. |
userName |
string |
user@domain |
The requested user's username. NOTE: The userName must be unique across all SAP Concur products. If a userName is currently in use in any SAP Concur product, it cannot be assigned again unless the original occurrence is changed. For example, assume that a userName was assigned in error. That userName can only be used again if an admin (either manually or via import) renames the original occurrence, allowing the userName to be used again. The following characters cannot be used as a value for this record: % [ # ! * & ( ) ~ ' { ^ } \ / ? > < , ; : " + = ], and pipe. |
companyId |
string |
- | Required, if employeeNumber is used The ID of the company the user belongs to. |
employeeNumber |
string |
- | Required, if companyId is used User's employee number. |
externalId |
string |
- | User’s external ID. |
excludedAttributes |
string |
- | A multi-valued list of strings indicating the names of resource attributes to be removed from the default set of attributes to return. |
startIndex |
string |
- | The 1-based index of the first query result. Default: 1 |
count |
string |
- | The desired maximum number of query results per page. Maximum count: 100. Default: 10 |
Headers
Payload
None.
Response
Status Codes
- 200 OK
- 400 Bad Request
- 401 Unauthorized
- 404 Not Found
- 500 Internal Server Error
- 501 Not Implemented
- 502 Bad Gateway
- 503 Service Unavailable
- 504 Gateway Timeout
Headers
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7231 Content-Type
Payload
Example
Request
GET https://us.api.concursolutions.com/profile/identity/v4/users/
Accept: application/json
Authorization: BEARER {token}
Response
200 OK
Content-Type: application/json
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"totalResults": 107705,
"startIndex": 1,
"itemsPerPage": 20,
"Resources": [
{ User 1 …},
{User 2…},…
{User 20…}
]
}
Retrieve a User's Identity Profile
Retrieves a unique user based on the user’s UUID.
Request
URI
Template
GET https://us.api.concursolutions.com/profile/identity/v4/Users/
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
- | Requested user's UUID. |
Headers
Payload
None.
Response
Status Codes
- 200 OK
- 400 Bad Request
- 401 Unauthorized
- 404 Not Found
- 500 Internal Server Error
- 501 Not Implemented
- 502 Bad Gateway
- 503 Service Unavailable
- 504 Gateway Timeout
Headers
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7231 Content-Type
Payload
Example
Request
GET https://us.api.concursolutions.com/profile/identity/v4/Users/
Accept: application/json
Authorization: BEARER {token}
Response
200 OK
Content-Type: application/json
{
"active": true,
"addresses": [
{
"country": "string",
"locality": "string",
"postalCode": "string",
"region": "string",
"streetAddress": "string",
"type": "work"
}
],
"dateOfBirth": "string",
"displayName": "string",
"emails": [
{
"dateAdded": "string",
"dateVerified": "string",
"notifications": true,
"type": "work",
"value": "string",
"verified": true
}
],
"emergencyContacts": [
{
"country": "string",
"emails": [
"string"
],
"locality": "string",
"name": "string",
"phones": [
"string"
],
"postalCode": "string",
"region": "string",
"relationship": "Spouse",
"streetAddress": "string"
}
],
"entitlements": [
"Expense"
],
"externalId": "string",
"gender": "Male",
"id": "string",
"localeOverrides": {
"preference24Hour": "h:mm AM/PM",
"preferenceCurrencySymbolLocation": "BeforeAmount",
"preferenceDateFormat": "mm/dd/yyyy",
"preferenceDefaultCalView": "day",
"preferenceDistance": "mile",
"preferenceEndDayViewHour": 0,
"preferenceFirstDayOfWeek": "Monday",
"preferenceHourMinuteSeparator": ":",
"preferenceNegativeCurrencyFormat": "-100",
"preferenceNegativeNumberFormat": "-100",
"preferenceNumberFormat": "1,000.00",
"preferenceStartDayViewHour": 0
},
"meta": {},
"name": {
"familyName": "string",
"formatted": "string",
"givenName": "string",
"hasNoMiddleName": true,
"honorificPrefix": "Miss",
"honorificSuffix": "Jr.",
"legalName": "string",
"middleInitial": "string",
"middleName": "string"
},
"nickName": "string",
"phoneNumbers": [
{
"display": "string",
"notifications": true,
"operatingSystem": "Android Phone",
"primary": true,
"type": "work",
"value": "string"
}
],
"preferredLanguage": "string",
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"timezone": "string",
"title": "string",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"companyId": "string",
"costCenter": "string",
"department": "string",
"division": "string",
"employeeNumber": "string",
"manager": {
"$ref": "string",
"displayName": "string",
"employeeNumber": "string",
"value": "string"
},
"orgUnit": "string",
"organization": "string",
"self": {
"$ref": "string",
"displayName": "string",
"employeeNumber": "string",
"value": "string"
},
"startDate": "string",
"terminationDate": "string"
},
"userName": "string"
}
Create a User's Identity Profile
Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.
Creates a user's identity profile.
Request
URI
Template
POST https://us.api.concursolutions.com/profile/identity/v4/Users
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
user |
string |
- | The user identity to create. |
Headers
Payload
None.
Response
Status Codes
- 200 OK
- 400 Bad Request
- 401 Unauthorized
- 404 Not Found
- 500 Internal Server Error
- 501 Not Implemented
- 502 Bad Gateway
- 503 Service Unavailable
- 504 Gateway Timeout
Headers
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7231 Content-Type
- RFC 7235 Authorization
Payload
Example
Request
{
"userName": "SAPDemoUser_User222@example.com",
"active": true,
"name": {
"familyName": "SAPDemoUser",
"givenName": "User222"
},
"emails": [
{
"value": "SAPDemoUser_User222@example.com"
}
],
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"companyId": "aa076ada-80a9-4f57-8e98-9300b1c3171d"
}
}
Response
{
"meta": {
"resourceType": "User",
"created": "2020-08-14T23:07:02.000739Z",
"lastModified": "2020-08-14T23:07:02.000739Z",
"version": 0,
"location": "https://us.api.concursolutions.com/profile/identity/v4/users/b38316e0-e2f6-48c8-bb3b-193d4faef578"
},
"displayName": "User222",
"name": {
"familyName": "SAPDemoUser",
"givenName": "User222",
"formatted": "SAPDemoUser, User222 "
},
"phoneNumbers": [],
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
],
"active": true,
"id": "b38316e0-e2f6-48c8-bb3b-193d4faef578",
"emails": [
{
"value": "SAPDemoUser_User222@example.com"
}
],
"userName": "SAPDemoUser_User222@example.com",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"companyId": "aa076ada-80a9-4f57-8e98-9300b1c3171d"
}
}
Update a User's Identity Profile
Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.
Updates applicable attributes in the user's identity profile.
Request
URI
Template
PATCH https://us.api.concursolutions.com/profile/identity/v4/Users/UUID
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
- | The user's UUID. |
Headers
Payload
None.
Response
Status Codes
- 200 OK
- 400 Bad Request
- 401 Unauthorized
- 404 Not Found
- 500 Internal Server Error
- 501 Not Implemented
- 502 Bad Gateway
- 503 Service Unavailable
- 504 Gateway Timeout
Headers
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7231 Content-Type
- RFC 7235 Authorization
Payload
Example
Request
{
"Operations": [
{
"op": "add",
"path" : "externalId",
"value": "123-222"
}
]
}
Response
{
"localeOverrides": {
"preferenceEndDayViewHour": 20,
"preferenceFirstDayOfWeek": "Sunday",
"preferenceDateFormat": "mm/dd/yyyy",
"preferenceCurrencySymbolLocation": "BeforeAmount",
"preferenceHourMinuteSeparator": ":",
"preferenceDefaultCalView": "month",
"preference24Hour": "H:mm",
"preferenceNumberFormat": "1,000.00",
"preferenceStartDayViewHour": 8,
"preferenceNegativeCurrencyFormat": "-100"
},
"title": null,
"addresses": [
{
"country": "US",
"streetAddress": null,
"postalCode": null,
"locality": null,
"type": "home",
"region": null
},
{
"country": "US",
"streetAddress": null,
"postalCode": null,
"locality": null,
"type": "work",
"region": null
}
],
"timezone": "America/New_York",
"meta": {
"resourceType": "User",
"created": "2020-08-14T23:07:02.000739Z",
"lastModified": "2020-08-14T23:07:04.000900Z",
"version": 2,
"location": "https://us.api.concursolutions.com/profile/identity/v4/users/b38316e0-e2f6-48c8-bb3b-193d4faef578"
},
"displayName": "User222",
"name": {
"honorificSuffix": null,
"hasNoMiddleName": true,
"formatted": "SAPDemoUser, User222 ",
"familyName": "SAPDemoUser",
"givenName": "User222",
"honorificPrefix": null,
"middleName": null
},
"phoneNumbers": [],
"emergencyContacts": [
{
"country": null,
"streetAddress": null,
"postalCode": null,
"name": null,
"locality": null,
"phones": [],
"region": null,
"relationship": "Other"
}
],
"preferredLanguage": "en-US",
"dateOfBirth": null,
"nickName": null,
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
],
"externalId": "123-222",
"active": true,
"id": "b38316e0-e2f6-48c8-bb3b-193d4faef578",
"gender": null,
"emails": [],
"userName": "SAPDemoUser_User222@example.com",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"terminationDate": null,
"companyId": "aa076ada-80a9-4f57-8e98-9300b1c3171d",
"manager": null,
"costCenter": null,
"orgUnit": null,
"startDate": "2020-08-14T23:07:00.000",
"employeeNumber": null
}
}
Replace a User's Identity Profile
Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.
Replaces a user's identity profile.
Request
URI
Template
PUT https://us.api.concursolutions.com/profile/identity/v4/Users/UUID
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
- | The user's UUID. |
user |
string |
- | The user identity to update. |
Headers
Payload
Response
Status Codes
- 200 OK
- 400 Bad Request
- 401 Unauthorized
- 404 Not Found
- 500 Internal Server Error
- 501 Not Implemented
- 502 Bad Gateway
- 503 Service Unavailable
- 504 Gateway Timeout
Headers
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7231 Content-Type
- RFC 7235 Authorization
Payload
Example
Request
{
"active": true,
"addresses": [
{
"country": "string",
"locality": "string",
"postalCode": "string",
"region": "string",
"streetAddress": "string",
"type": "work"
}
],
"dateOfBirth": "string",
"displayName": "string",
"emails": [
{
"dateAdded": "string",
"dateVerified": "string",
"notifications": true,
"type": "work",
"value": "string",
"verified": true
}
],
"emergencyContacts": [
{
"country": "string",
"emails": [
"string"
],
"locality": "string",
"name": "string",
"phones": [
"string"
],
"postalCode": "string",
"region": "string",
"relationship": "Spouse",
"streetAddress": "string"
}
],
"entitlements": [
"Expense"
],
"externalId": "string",
"gender": "Male",
"id": "string",
"localeOverrides": {
"preference24Hour": "h:mm AM/PM",
"preferenceCurrencySymbolLocation": "BeforeAmount",
"preferenceDateFormat": "mm/dd/yyyy",
"preferenceDefaultCalView": "day",
"preferenceDistance": "mile",
"preferenceEndDayViewHour": 0,
"preferenceFirstDayOfWeek": "Monday",
"preferenceHourMinuteSeparator": ":",
"preferenceNegativeCurrencyFormat": "-100",
"preferenceNegativeNumberFormat": "-100",
"preferenceNumberFormat": "1,000.00",
"preferenceStartDayViewHour": 0
},
"meta": {},
"name": {
"academicTitle": [
"Dr."
],
"familyName": "string",
"familyNamePrefix": "string",
"formatted": "string",
"givenName": "string",
"hasNoMiddleName": true,
"honorificPrefix": "Miss",
"honorificSuffix": "Jr.",
"legalName": "string",
"middleInitial": "string",
"middleName": "string"
},
"nickName": "string",
"phoneNumbers": [
{
"display": "string",
"notifications": true,
"operatingSystem": "Android Phone",
"primary": true,
"type": "work",
"value": "string"
}
],
"preferredLanguage": "string",
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"timezone": "string",
"title": "string",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"companyId": "string",
"costCenter": "string",
"department": "string",
"division": "string",
"employeeNumber": "string",
"manager": {
"$ref": "string",
"displayName": "string",
"employeeNumber": "string",
"value": "string"
},
"orgUnit": "string",
"organization": "string",
"self": {
"$ref": "string",
"displayName": "string",
"employeeNumber": "string",
"value": "string"
},
"startDate": "string",
"terminationDate": "string"
},
"userName": "string"
}
Response
{
"meta": {
"resourceType": "User",
"created": "2020-08-14T23:07:02.000739Z",
"lastModified": "2020-08-14T23:07:02.000739Z",
"version": 0,
"location": "https://us.api.concursolutions.com/profile/identity/v4/users/b38316e0-e2f6-48c8-bb3b-193d4faef578"
},
"displayName": "User222",
"name": {
"familyName": "SAPDemoUser",
"givenName": "User222",
"formatted": "SAPDemoUser, User222 "
},
"phoneNumbers": [],
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
],
"active": true,
"id": "b38316e0-e2f6-48c8-bb3b-193d4faef578",
"emails": [
{
"value": "SAPDemoUser_User222@example.com"
}
],
"userName": "SAPDemoUser_User222@example.com",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"companyId": "aa076ada-80a9-4f57-8e98-9300b1c3171d"
}
}
Schema
User
| Name | Type | Format | Description |
|---|---|---|---|
active |
boolean |
true/false |
Required If true, the user is active. |
addresses |
object |
- | A physical mailing address for this user. Examples: work, home, other |
addresses.country |
string |
- | A two-letter country code defined in ISO 3166-1 alpha-2. |
addresses.locality |
string |
- | The city or locality. |
addresses.postalCode |
string |
- | The zip code or postal code. |
addresses.region |
string |
- | The state or region. |
addresses.streetAddress |
string |
- | The full street address component, which may include house number, street name, P.O. box, and multi-line extended street address information. |
addresses.type |
string |
- | A label indicating the function of the address. Examples: work, home |
dateOfBirth |
string |
YYYY-MM-DD |
The user's date of birth. |
displayName |
string |
- | The name of the user, suitable for public display. |
emails |
object |
- | Required Email addresses for the user. The value should be canonicalized by the service provider. |
dateAdded |
string |
- | The date and time the email was added to the user's profile. |
dateVerified |
string |
- | The date and time the email was verified. |
emails.notifications |
boolean |
true/false |
If true, notifications have been opted-in for emails. |
emails.type |
string |
- | A label indicating the attribute's function. Examples: work, home |
emails.value |
string |
- | Required Email address value. |
emails.verified |
boolean |
true/false |
If true, the email has been verified by the user. |
emergencyContacts |
object |
- | Emergency contact information for the user. |
emergencyContacts.country |
string |
- | A two-letter country code defined in ISO 3166-1 alpha-2. |
emergencyContacts.emails |
string |
- | Emails of the emergency contact. |
emergencyContacts.locality |
string |
- | The city or locality of the emergency contact. |
emergencyContacts.name |
string |
- | Required The emergency contact's name. |
emergencyContacts.phones |
string |
- | Phone numbers of the emergency contact. |
emergencyContacts.postalCode |
string |
- | The zip code or postal code of the emergency contact. |
emergencyContacts.region |
string |
- | The state or region of the emergency contact. |
emergencyContacts.relationship |
string |
- | Required The emergency contact's relationship to the user. Supported values: Spouse, Brother, Parent, Sister, Life Partner, Other |
emergencyContacts.streetAddress |
string |
- | The full street address component, which may include house number, street name, P.O. box, and multi-line extended street address information. |
entitlements |
string |
- | The features enabled for the user. Supported values: Expense, Invoice, Locate, Request, Travel |
externalId |
string |
- | User identifier from the provisioning client. |
gender |
string |
- | The user's gender. |
id |
string |
- | Required. Read Only Unique identifier for the user, also known as the UUID. |
localeOverrides |
object |
- | Read Only Support for users who want to override locale settings. |
localeOverrides.preference24Hour |
string |
- | Preferred 24 hour format for the user. Supported values: h:mm AM/PM, H:mm |
localeOverrides.preferenceCurrencySymbolLocation |
string |
- | Preferred currency symbol location for the user. Supported values: BeforeAmount, AfterAmount |
localeOverrides.preferenceDateFormat |
string |
- | Preferred date format for the user. |
localeOverrides.preferenceDefaultCalView |
string |
- | Preferred default calendar view for the user. Supported values: day, week, month |
localeOverrides.preferenceDistance |
string |
- | Preferred distance metric. Supported values: mile, km |
localeOverrides.preferenceEndDayViewHour |
integer |
- | Preferred hour setting for the end of day. Supported values: 0-23 |
localeOverrides.preferenceFirstDayOfWeek |
string |
- | Preferred first day of the week for the user. |
localeOverrides.preferenceHourMinuteSeparator |
string |
- | Preferred separator between hour and minute. Supported values: :, . |
localeOverrides.preferenceNegativeCurrencyFormat |
string |
- | Preferred negative currency format for the user. |
localeOverrides.preferenceNegativeNumberFormat |
string |
- | Preferred negative number format for the user. |
localeOverrides.preferenceNumberFormat |
string |
- | Preferred number format for the user. |
localeOverrides.preferenceStartDayViewHour |
integer |
- | Preferred start of day for the user, from 1. |
meta |
object |
- | Read Only |
name |
object |
- | Required The user's name. |
name.academicTitle |
string |
- | Title signifying level of academic achievement. |
familyName |
string |
- | Required The family or last name of the user. |
name.familyName |
string |
- | Required The family or last name of the user. |
name.familyNamePrefix |
string |
- | The family name prefix of the user, if applicable. |
name.formatted |
string |
- | The full name of the user, formatted for display. Example: Jensen, Barbara Jane |
name.givenName |
string |
- | Required The given or first name of the user. |
name.hasNoMiddleName |
boolean |
true/false |
If true, the user has a middle name. |
name.honorificPrefix |
string |
- | The honorific or title prefix(es) of the user. |
name.honorificSuffix |
string |
- | The honorific suffix(es) of the user. |
name.legalName |
string |
- | The legal name of the user. |
name.middleInitial |
string |
- | The middle initial of the user, if applicable. |
name.middleName |
string |
- | The middle name(s) of the user, if applicable. |
name.nickName |
string |
- | The casual way to address the user. This attribute should not be used to represent a user's username. |
phoneNumbers |
object |
- | Phone numbers for the user. The value should be canonicalized by the service provider according to the format specified in RFC 3966. Duplicates are not allowed for types other than mobile. |
phoneNumbers.display |
string |
- | A human-readable phone number for display. |
phoneNumbers.notifications |
boolean |
true/false |
If true, notifications have been opted in for phone numbers. This is only available for mobile phone numbers. |
phoneNumbers.operatingSystem |
string |
- | The operating system of the device, when the phone is a cellphone type. |
phoneNumbers.primary |
boolean |
true/false |
If true, this is the primary mobile device. This is only available for mobile phone numbers. One mobile phone number must be set as the primary number and only one phone number can be set to primary at a time. |
phoneNumbers.type |
string |
- | A label indicating the attribute's function. Examples: work, home, mobile |
phoneNumbers.value |
string |
- | Required The phone number value. |
preferredLanguage |
string |
- | Indicates the user's preferred written or spoken language. |
timezone |
string |
- | The user's time zone in the Olson time zone database format. Example: America/Los_Angeles |
title |
string |
- | The user's job title in the company. |
companyId |
string |
- | Required. Immutable The SAP Concur ID of the company. |
costCenter |
string |
- | The employee cost center for product. The value of this parameter is provisioned and is not related to the Concur Expense costCenter. |
department |
string |
- | Client supplied department name. The value of this parameter is provisioned and is not related to the Concur Expense department. |
division |
string |
- | Client supplied division name. The value of this parameter is provisioned and is not related to the Concur Expense division. |
employeeNumber |
string |
- | Client supplied employee number within the company, unique for the company. |
manager |
object |
- | The manager of this user. |
$ref |
string |
- | The URI of the SCIM resource representing the referenced user. |
displayName |
string |
- | Read Only The referenced user's display name. |
employeeNumber |
string |
- | The referenced user's employee number, if it is an Enterprise user. |
value |
string |
- | The referenced user's UUID. |
orgUnit |
string |
- | Client supplied org unit name. The value of this parameter is provisioned and is not related to the Concur Expense orgUnit. |
organization |
string |
- | Read Only The company name. |
self |
object |
- | A reference to this user. |
$ref |
string |
- | The URI of the SCIM resource representing the referenced user. |
displayName |
string |
- | Read Only The referenced user's display name. |
employeeNumber |
string |
- | The referenced user's employee number, if it is an Enterprise user. |
value |
string |
- | The referenced user's UUID. |
startDate |
string |
YYYY-MM-DD |
The user's start date. |
terminationDate |
string |
YYYY-MM-DD |
The user's termination date. |
userName |
string |
user@domain |
Required The name that can be used to login to Concur Travel and Expense. NOTE: The userName must be unique across all SAP Concur products. If a userName is currently in use in any SAP Concur product, it cannot be assigned again unless the original occurrence is changed. For example, assume that a userName was assigned in error. That userName can only be used again if an admin (either manually or via import) renames the original occurrence, allowing the userName to be used again. The following characters cannot be used as a value for this record: % [ # ! * & ( ) ~ ' { ^ } \ / ? > < , ; : " + = ] and pipe |
UserList
| Name | Type | Format | Description |
|---|---|---|---|
totalResults |
integer |
- | The total number of results matching the client query. |
itemsPerPage |
integer |
- | The number of query results returned in a query response page. |
startIndex |
integer |
- | The 1-based index of the first result in the current set of query results. |
Resources |
User |
- | - |
Company
| Name | Type | Format | Description |
|---|---|---|---|
active |
boolean |
true/false |
Required If true, the company is active. |
addresses |
object |
- | - |
country |
string |
- | A two-letter country code defined in ISO 3166-1 alpha-2. |
locality |
string |
- | The city or locality of the company address. |
postalCode |
string |
- | The zip code or postal code of the company address. |
region |
string |
- | The state or region of the company address. |
streetAddress |
string |
- | The full street address component, which may include house number, street name, P.O. box, and multi-line extended street address information. |
companyDomain |
string |
- | The company's company domain name. |
contact |
object |
- | - |
country |
string |
- | A two-letter country code defined in ISO 3166-1 alpha-2. |
emails |
string |
- | Emails of the contact. |
locality |
string |
- | The city or locality of the contact. |
name |
string |
- | Required Name of the contact. |
phones |
string |
- | Phone numbers of the contact. |
postalCode |
string |
- | The zip code or postal code of the contact. |
region |
string |
- | The state or region. |
streetAddress |
string |
- | The full street address component, which may include house number, street name, P.O. box, and multi-line extended street address information. |
defaultLanguage |
string |
- | Indicates the default language for the company. |
entitlements |
string |
- | The features enabled for the company. Supported values: Expense, Invoice, Locate, Request, Travel |
id |
string |
- | Required Unique identifier for the company, also known as the company UUID. |
internetDomain |
string |
- | The company's internet domain name. |
meta |
object |
- | - |
name |
string |
- | The name of the company. |
schemas |
string |
- | Read Only |
loginPolicy |
object |
- | - |
hideForgotLoginIdLink |
boolean |
true/false |
If true, the Forgot LoginId Link will be hidden. |
loginFailureLockoutDuration |
integer |
- | The duration of the login failure lockout. |
loginFailureWindowDuration |
integer |
- | The window duration of the login failure. |
loginFailuresAllowed |
integer |
- | The amount of login failures allowed. |
loginIPRestriction |
string |
- | The login IP restrictions. |
loginOneTimeLinkExpirationLength |
integer |
- | The length of the one time login expiration link. |
loginViaSsoOnly |
boolean |
true/false |
If true, the login is available via SSO only. |
passwordPolicy |
object |
- | - |
daysUntilExpiration |
integer |
- | Number of days until password expiration. |
expirePasswordOnUserCreation |
boolean |
true/false |
If true, the password will expire on user creation. |
maxLength |
integer |
- | Maximum length of the password. |
minLength |
integer |
- | Minimum length of the password. |
mobileAuthenticationLifetime |
integer |
- | The mobile session timeout in seconds. |
mobileMinLength |
integer |
- | The minimum length of the password for mobile. |
mobileRequiresMixedCase |
boolean |
true/false |
If true, the password will require mixed cases for mobile. |
mobileRequiresNonalphanum |
boolean |
true/false |
If true, the password will require non-alphanumeric characters for mobile. |
numGenerationsBeforeCanReuse |
integer |
- | Number of generations before the password can be reused. |
numSecurityQuestions |
integer |
- | The number of required security questions. |
numSecurityQuestionsUsersPick |
integer |
- | The number of security questions users can pick. |
passwordResetEmailPolicy |
string |
- | When the password reset email should be sent. Supported values: never, anyTime, afterFirstLogin |
passwordResetSupportEmail |
string |
- | The from address of the password or PIN reset email. |
requiresMixedCase |
boolean |
true/false |
If true, the password will require mixed cases. |
requiresNonAlpha |
boolean |
true/false |
If true, the password will requires non-alphabetic characters. |
requiresNonAlphanum |
boolean |
true/false |
If true, the password will require non-alphanumeric characters. |
requiresNumber |
boolean |
true/false |
If true, the password will require numbers. |
requiresSecurityQuestions |
boolean |
true/false |
If true , security questions will be required. |
restrictPasswordResetOncePerDay |
boolean |
true/false |
If true, password resets will be limited to once a day. |
channels |
string |
- | - |
enabled |
boolean |
true/false |
If true, channels will be enabled. |
tenantIdSpend |
string |
- | The ID of the spend tenant for the company. |
tenantIdTravel |
string |
- | The ID of the travel tenant for the company. |
Schema Extension
| Name | Type | Format | Description |
|---|---|---|---|
schema |
string |
- | Required The string identifier of the extension. |
required |
boolean |
true/false |
Required If true, this extension is a required part of the schema. |
Resource Type
| Name | Type | Format | Description |
|---|---|---|---|
attributes |
SchemaExtension |
- | Required The resource's extensions. |
description |
string |
- | Required The resource's description. |
endpoint |
string |
- | Required The resource's HTTP addressable endpoint relative to the base URL. Example: /Users |
id |
string |
- | Required The resource's ID. |
name |
string |
- | Required The resource's name. Example: User |
schema |
string |
- | Required The resource's associated schema. |
Authenticated Schemas
| Name | Type | Format | Description |
|---|---|---|---|
description |
string |
- | Required The description of the authentication schema. |
documentationUrl |
string |
- | Required An HTTP addressable URL pointing to the authentication schema's usage documentation. |
name |
string |
- | Required The common authentication schema name. Example: HTTP Basic |
specUrl |
string |
- | Required An HTTP addressable URL pointing to the authentication schema's specification. |
Service Provider Config
| Name | Type | Format | Description |
|---|---|---|---|
authenticationSchemes |
AuthenticationSchemes |
- | Required Specifies supported authentication schema properties. |
bulk |
ServiceProviderConfigSetting |
- | Required Details about the feature support for the service provider. |
changePassword |
ServiceProviderConfigSetting |
- | Required Details about the feature support for the service provider. |
documentationUrl |
string |
- | Required An HTTP addressable URL pointing to the service provider's help documentation. |
etag |
ServiceProviderConfigSetting |
- | Required Details about the feature support for the service provider. |
filter |
ServiceProviderConfigSetting |
- | Required Details about the feature support for the service provider. |
patch |
ServiceProviderConfigSetting |
- | Required Details about the feature support for the service provider. |
sort |
ServiceProviderConfigSetting |
- | Required Details about the feature support for the service provider. |
Service Provider Config Setting
| Name | Type | Format | Description |
|---|---|---|---|
supported |
boolean |
true/false |
If true, the feature is supported. |
Concur Error
| Name | Type | Format | Description |
|---|---|---|---|
messages |
object |
- | Additional messages in case of errors/warnings. |
code |
string |
- | Required The error message code. |
message |
string |
- | The error message description. |
schemaPath |
string |
- | The relative schema path of attribute. |
type |
string |
- | Required The error message type. Supported values: error, warning |
Error Response
| Name | Type | Format | Description |
|---|---|---|---|
scimType |
string |
- | The SCIM detail error keyword. |
detail |
string |
- | The human readable message. |
status |
string |
- | Required The HTTP status code. |
Identity v4 Scope Mapping
Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.
User
| Name | Scope |
|---|---|
active |
identity.user.core.read, identity.user.coreenterprise.writeonly |
addresses |
identity.user.coresensitive.read, identity.user.coreenterprise.writeonly |
country |
identity.user.coresensitive.read, identity.user.coreenterprise.writeonly |
locality |
identity.user.coresensitive.read, identity.user.coreenterprise.writeonly |
postalCode |
identity.user.coresensitive.read, identity.user.coreenterprise.writeonly |
region |
identity.user.coresensitive.read, identity.user.coreenterprise.writeonly |
streetAddress |
identity.user.coresensitive.read, identity.user.coreenterprise.writeonly |
type |
identity.user.coresensitive.read, identity.user.coreenterprise.writeonly |
dateOfBirth |
identity.user.coresensitive.read, identity.user.coreenterprise.writeonly |
displayName |
identity.user.core.read, identity.user.coreenterprise.writeonly |
emails |
identity.user.coresensitive.read, identity.user.coreenterprise.writeonly |
dateAdded |
identity.user.coresensitive.read, identity.user.coreenterprise.writeonly |
dateVerified |
identity.user.coresensitive.read, identity.user.coreenterprise.writeonly |
notifications |
identity.user.coresensitive.read, identity.user.coreenterprise.writeonly |
type |
identity.user.coresensitive.read, identity.user.coreenterprise.writeonly |
value |
identity.user.coresensitive.read, identity.user.coreenterprise.writeonly |
verified |
identity.user.coresensitive.read, identity.user.coreenterprise.writeonly |
emergencyContacts |
identity.user.coresensitive.read, identity.user.coreenterprise.writeonly |
country |
identity.user.coresensitive.read, identity.user.coreenterprise.writeonly |
emails |
identity.user.coresensitive.read, identity.user.coreenterprise.writeonly |
locality |
identity.user.coresensitive.read, identity.user.coreenterprise.writeonly |
name |
identity.user.core.read, identity.user.coreenterprise.writeonly |
phones |
identity.user.coresensitive.read, identity.user.coreenterprise.writeonly |
postalCode |
identity.user.coresensitive.read, identity.user.coreenterprise.writeonly |
region |
identity.user.coresensitive.read, identity.user.coreenterprise.writeonly |
relationship |
identity.user.coresensitive.read, identity.user.coreenterprise.writeonly |
streetAddress |
identity.user.coresensitive.read, identity.user.coreenterprise.writeonly |
entitlements |
identity.user.enterprise.read, identity.user.coreenterprise.writeonly |
externalId |
identity.user.ids.read, identity.user.externalID.writeonly |
gender |
identity.user.coresensitive.read, identity.user.coreenterprise.writeonly |
id |
identity.user.ids.read, identity.user.core.read |
localeOverrides |
identity.user.core.read, identity.user.coreenterprise.writeonly |
preference24Hour |
identity.user.core.read, identity.user.coreenterprise.writeonly |
preferenceCurrencySymbolLocation |
identity.user.core.read, identity.user.coreenterprise.writeonly |
preferenceDateFormat |
identity.user.core.read, identity.user.coreenterprise.writeonly |
preferenceDefaultCalView |
identity.user.core.read, identity.user.coreenterprise.writeonly |
preferenceDistance |
identity.user.core.read, identity.user.coreenterprise.writeonly |
preferenceEndDayViewHour |
identity.user.core.read, identity.user.coreenterprise.writeonly |
preferenceFirstDayOfWeek |
identity.user.core.read, identity.user.coreenterprise.writeonly |
preferenceHourMinuteSeparator |
identity.user.core.read, identity.user.coreenterprise.writeonly |
preferenceNegativeCurrencyFormat |
identity.user.core.read, identity.user.coreenterprise.writeonly |
preferenceNegativeNumberFormat |
identity.user.core.read, identity.user.coreenterprise.writeonly |
preferenceNumberFormat |
identity.user.core.read, identity.user.coreenterprise.writeonly |
preferenceStartDayViewHour |
identity.user.core.read, identity.user.coreenterprise.writeonly |
meta |
identity.user.core.read, identity.user.coreenterprise.writeonly |
name |
identity.user.core.read, identity.user.coreenterprise.writeonly |
academicTitle |
identity.user.core.read, identity.user.coreenterprise.writeonly |
familyName |
identity.user.core.read, identity.user.coreenterprise.writeonly |
familyNamePrefix |
identity.user.core.read, identity.user.coreenterprise.writeonly |
formatted |
identity.user.core.read, identity.user.coreenterprise.writeonly |
givenName |
identity.user.core.read, identity.user.coreenterprise.writeonly |
hasNoMiddleName |
identity.user.core.read, identity.user.coreenterprise.writeonly |
honorificPrefix |
identity.user.core.read, identity.user.coreenterprise.writeonly |
honorificSuffix |
identity.user.core.read, identity.user.coreenterprise.writeonly |
legalName |
identity.user.core.read, identity.user.coreenterprise.writeonly |
middleInitial |
identity.user.core.read, identity.user.coreenterprise.writeonly |
middleName |
identity.user.core.read, identity.user.coreenterprise.writeonly |
nickName |
identity.user.core.read, identity.user.coreenterprise.writeonly |
phoneNumbers |
identity.user.coresensitive.read, identity.user.coreenterprise.writeonly |
display |
identity.user.coresensitive.read, identity.user.coreenterprise.writeonly |
notifications |
identity.user.coresensitive.read, identity.user.coreenterprise.writeonly |
operatingSystem |
identity.user.coresensitive.read, identity.user.coreenterprise.writeonly |
primary |
identity.user.coresensitive.read, identity.user.coreenterprise.writeonly |
type |
identity.user.coresensitive.read, identity.user.coreenterprise.writeonly |
value |
identity.user.coresensitive.read, identity.user.coreenterprise.writeonly |
preferredLanguage |
identity.user.core.read, identity.user.coreenterprise.writeonly |
timezone |
identity.user.core.read, identity.user.coreenterprise.writeonly |
title |
identity.user.core.read, identity.user.coreenterprise.writeonly |
companyId |
identity.user.enterprise.read, identity.user.coreenterprise.writeonly |
costCenter |
identity.user.enterprise.read, identity.user.coreenterprise.writeonly |
department |
identity.user.enterprise.read, identity.user.coreenterprise.writeonly |
division |
identity.user.enterprise.read, identity.user.coreenterprise.writeonly |
employeeNumber |
identity.user.enterprise.read, identity.user.coreenterprise.writeonly |
manager |
identity.user.enterprise.read, identity.user.coreenterprise.writeonly |
$ref |
identity.user.core.read |
displayName |
identity.user.core.read, identity.user.coreenterprise.writeonly |
employeeNumber |
identity.user.enterprise.read, identity.user.coreenterprise.writeonly |
value |
identity.user.coreenterprise.writeonly |
orgUnit |
identity.user.enterprise.read, identity.user.coreenterprise.writeonly |
organization |
identity.user.enterprise.read, identity.user.coreenterprise.writeonly |
self |
identity.user.enterprise.read, identity.user.coreenterprise.writeonly |
$ref |
identity.user.core.read |
displayName |
identity.user.core.read, identity.user.coreenterprise.writeonly |
employeeNumber |
identity.user.enterprise.read, identity.user.coreenterprise.writeonly |
value |
identity.user.coreenterprise.writeonly |
startDate |
identity.user.enterprise.read, identity.user.coreenterprise.writeonly |
terminationDate |
identity.user.enterprise.read, identity.user.coreenterprise.writeonly |
userName |
identity.user.coreenterprise.writeonly, identity.user.ids.read |
REALTIME-LOCATION-INGEST
Realtime Ingest Location
Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.
Overview
This API provides an endpoint to ingest real time user location information from Rideshare Services.
Regional Availability
https://us.api.concursolutions.com/realtimeingest
Request Headers
Request Payload
Please refer the Schema section for more information regarding each field in the payload.
Response Headers
- [concur-correlationid] Concur specific custom header
- RFC 7231 Content-Type
- RFC 7230 Content-Length
- RFC 7231 Date
- RFC 7231 Server
Response Payload
| Name | Type | Format | Description |
|---|---|---|---|
| concur-correlationId | String | - | Concur specific custom field |
| requestId | String | - | Unique ID for the request |
| appVersion | String | - | Application version number |
| message | String | - | Success / Error message |
| errorDescription | Object | JSON | Description of error, if applicable |
Status Codes
Example
Request URL
https://{baseURI}/location/{uuid}
Request
POST https://{baseURI}/location/{uuid}
Content-Type: application/json
Authorization: Bearer {access-token}
{
"uuid": "uuid",
"dropOffDateTime": "2018-06-08T09:00:45-0600",
"dropOffLocation": {
"latitude": 47.610378,
"longitude": -122.200676,
"name": "Bellevue",
"address": {
"streetAddress": "601 108th Ave NE",
"addressCountry": "US",
"addressLocality": "Bellevue",
"addressRegion": "WA",
"postalCode": "98004"
}
}
}
Response Header
Date: Mon, 11 Jun 2018 17:43:28 GMT
Server: pproxy/d8b665e
Content-Length: 170
Content-Type: application/json
concur-correlationid: {concur-correlationid}
Response Body
{
"concur-correlationId": "concur-correlationId",
"requestId": "requestId",
"appVersion": "appVersion",
"message": "Event Received"
}
Schema
See the schema documentation below for the specifications of each type, plus the various schemas that are shared components of each receipt schema.
The user locations API includes users and itineraries (locations) in addition to information about the company and post type (add or cancel).
| Property Name | Type | Format | Description |
|---|---|---|---|
| uuid | String | - | Required UUID of the user. |
| dropOffDateTime | String | DateTime | Required Date Time where the user was dropped off (in RFC3339 format) |
| dropOffLocation | Object | JSON | Required Location where the user was dropped off |
dropOffLocation
| Property Name | Type | Format | Description |
|---|---|---|---|
| name | String | - | Canonical name of the location. |
| latitude | Number | Float | Required Numeric value of latitude (Range -90.00 and 90.00) |
| longitude | Number | Float | Required Numeric value of longitude (Range -180.00 and 180.00) |
| address | Object | JSON | Address where the user was dropped off |
address
| Property Name | Type | Format | Description |
|---|---|---|---|
| streetAddress | String | - | Street address of the location. |
| addressLocality | String | - | Canonical City name of the address |
| addressRegion | String | - | 1 to 3 character country subdivision code as defined in ISO 3166-2:2013 |
| addressCountry | String | - | 2 or 3 character country code as defined in ISO 3166-1:2013 |
| postalCode | String | - | Postal code of the address |
errorDescription
| Property Name | Type | Format | Description |
|---|---|---|---|
| fieldName | Array | - | Errors associated with the given fieldName |
RECEIPTS
Receipts v4 - Get Started
Overview
The Receipts V4 API accepts three different formulae for posting a receipt:
- Receipt Data - Your receipt data is stored along with an automatically generated receipt image file.
- Receipt Data & Receipt Image - Your receipt data and receipt image file are stored.
- Receipt Image w/o Data - Your receipt image file is stored along with some accompanying metadata.
All of the above are receipt resources, but the service draws a distinction between resources with data versus resources that are standalone images.
Resources with data are schema-enforced and are referred to as e-receipts.
Resources of standalone images are referred to as Image-Only Receipts.
These two different resources are sent/fetched from the Receipts V4 API via different endpoints: * E-Receipts (Receipts With Data) - Use E-Receipt Endpoints * Image-Only Receipts (Standalone Images Without Data) - Use Image-Only Receipt Endpoints
Note: The Receipts V4 API only provides GET access to individual or user’s receipts that have been submitted through this API, and, therefore the response will not be comprehensive of every user receipt within SAP Concur. All other images should be obtained via the Image v1 API. Additionally, only the receipts will be returned, there will not be any corresponding entry data. Examples of Enterprise apps that should use the Image v1 API include: ERP integrations for financial journal entry postings, VAT reclaim integrations that obtain transactions to calculate VAT reclaim, project billing integrations used to substantiate expenses billed back, etc.
Important Usage Restrictions
SAP Concur systems and clients rely on e-receipts to be legally valid tax documents in the relevant government jurisdictions. Use of the Receipts endpoint to post e-receipts must therefore meet the following criteria:
- The e-receipt must come directly from the original merchant issuing the receipt or from a third party authorized by the merchant to issue receipts on behalf of the merchant.
- All receipt data fields that are required by the relevant government jurisdiction must be provided even if the SAP Concur documentation indicates the data field is optional. If a government required data field is not available in the current schema then a legally compliant receipt image must be attached.
Overview of Version 4.0
Version 4.0 of the Receipts API offers features like more receipt types, automatic e-receipt generation in end user’s preferred language and ability for partners to provide detailed tax information. Unlike version 3.0, we are discontinuing the use of matching facts; instead the partner will have to create a receipt for a specific end user. Receipts 4.0 works only with the new Authentication API.
Explore the API
Prerequisites
Read the Getting Started section of Authentication API.
Once you have registered your application, read about the API endpoints, or click the button to download a request collection for Postman.
Retrieve a User Access Token:
Before making requests to the Receipts API, you must obtain an access token from the Authentication API.
The response will include an access_token field, which contains your access token. For subsequent calls, you will need to include this access token in the Authorization header of your calls. An id_token will be also included in the response. In order to retrieve the unique ID for your user, you will have to decode this id_token at jwt.io. You will need this ID in order to post receipts.
Examples:
cURL:
curl -d "client_secret={YOUR SECRET}&client_id={YOUR CLIENT ID}&grant_type=password&username={YOUR USERNAME}&password={YOUR PASSWORD}" https://us.api.concursolutions.com/oauth2/v0/token
HTTPie:
http -f POST https://us.api.concursolutions.com/oauth2/v0/token client_secret={YOUR SECRET} client_id={YOUR CLIENT ID} grant_type=password username={YOUR USERNAME} password=P{YOUR PASSWORD}
Explore the API in JavaScript
Below are some simple NodeJS code snippets for getting a token and posting a receipt.
Retrieve a User Access Token:
'use strict';
const request = require('request');
request.post({
url:'https://us.api.concursolutions.com/oauth2/v0/token',
form: {
client_secret: 'YOUR VALUE HERE',
client_id: 'YOUR VALUE HERE',
username: 'YOUR VALUE HERE',
password: 'YOUR VALUE HERE',
grant_type: 'password'
}},
(err, httpResponse, body) => {
if(err) { console.log(err); }
console.log('Status:', httpResponse.statusCode);
console.log('Response:', body);
});
Post a Receipt
'use strict';
const https = require('https');
const ACCESS_TOKEN = 'YOUR ACCESS TOKEN HERE';
const USER_ID = 'YOUR VALUE HERE';
const receipt = JSON.stringify(YOUR_RECEIPT_HERE);
const options = {
hostname: 'us.api.concursolutions.com',
path: `/receipts/v4/users/${USER_ID}`,
method: 'POST',
headers: {
'Authorization': `Bearer ${ACCESS_TOKEN}`,
'Content-Type': 'application/json',
'Content-Length': Buffer.byteLength(receipt),
'Link': '<http://schema.concursolutions.com/general-receipt.schema.json>;rel=describedBy'
}
};
const req = https.request(options, (res) => {
console.log('statusCode:', res.statusCode);
console.log('headers:', res.headers);
res.on('data', (data) => {
process.stdout.write(data);
});
});
req.write(receipt);
req.end();
req.on('error', (e) => {
console.error(e);
});
Endpoints
Definitions of Resources
- E-Receipt - A schema-enforced resource with data and, optionally, an image. If an image is not provided, one will be generated from the data resource.
- Image-Only Receipt - A standalone image without data.
Note: The Receipts V4 API only provides GET access to individual or user’s receipts that have been submitted through this API, and, therefore the response will not be comprehensive of every user receipt within SAP Concur. All other images should be obtained via the Image v1 API. Additionally, only the receipts will be returned, there will not be any corresponding entry data. Examples of Enterprise apps that should use the Image v1 API include: ERP integrations for financial journal entry postings, VAT reclaim integrations that obtain transactions to calculate VAT reclaim, project billing integrations used to substantiate expenses billed back, etc.
Supported Image Formats
- Image size must not exceed 25MB.
- Images with any dimension exceeding 2,200 pixels will be reduced, with the longest dimension reduced to 2,200 pixels and the remaining dimensions scaled down using a fixed aspect ratio.
- Image must be one of the supported file types: image/png, image/jpg, image/jpeg, image/tiff, image/tif, image/gif, and application/pdf. Images provided in image/tiff and image/tif will be converted to a PDF document with the image embedded within.
General
| Endpoint | Response Format | Request Summary |
|---|---|---|
| GET / | JSON | Get service index URLs |
| GET /v4/status/:receiptId | JSON | Get the status of a receipt |
Endpoint: Service Index
GET /
Making a GET request to the root of the service will return a list of current endpoints. If endpoint URLs ever change, the service index will be updated. To ensure that you are using the correct URLs, the safest practice is to check the service index before every request. The response will include current URLs for all endpoints in the receipt service.
Example Requests:
cURL:
curl -H "Authorization: Bearer {YOUR ACCESS TOKEN}" https://us.api.concursolutions.com/receipts/
HTTPie:
http https://us.api.concursolutions.com/receipts/ 'Authorization:Bearer {YOUR ACCESS TOKEN}'
Example Response:
{
"links": [
{
"rel": "self",
"href": "https://us.api.concursolutions.com/receipts/v4"
},
{
"rel": "receipt-get",
"method": "GET",
"href": "https://us.api.concursolutions.com/receipts/v4/{receiptId}"
},
{
"rel": "receipt-post",
"method": "POST",
"href": "https://us.api.concursolutions.com/receipts/v4/users/{userId}"
},
{
"rel": "receipts-get-user",
"method": "GET",
"href": "https://us.api.concursolutions.com/receipts/v4/users/{userId}"
},
{
"rel": "schemas-get",
"method": "GET",
"href": "https://us.api.concursolutions.com/receipts/schemas"
}
]
}
E-Receipts
| Endpoint | Response Format | Request Summary |
|---|---|---|
| GET /schemas | JSON | Get currently supported receipt schemas |
| POST /v4/users/:userId | N/A | Post a receipt |
| GET /v4/users/:userId | JSON | Get a user's receipts |
| GET /v4/:receiptId | JSON | Get a receipt by ID |
| GET /v4/:receiptId/image | image file | Get a receipt image. |
Endpoint: Schemas
GET /schemas/:schemaId
| Parameter | Requirement | Value |
|---|---|---|
| schemaId | optional | The ID of the schema to be returned. |
The response to a GET request to /schemas will have a list of JSON validation schemas for available receipt types. An array of supportingSchemas is also returned, but these do not represent actual receipt types.
If a schema ID is provided, then only the schema with that ID will be returned, instead of the entire schema index. The ID's of schemas are not UUIDs, but are instead just the names of the schema with the extension .schema.json. For example, car-rental-receipt.schema.json or air-receipt.schema.json.
One of the receipt schemas must be included in the link header of receipt POST requests with the relationship of describedBy. This looks like link: <http://schema.concursolutions.com/{RECEIPT TYPE}.schema.json>;rel=describedBy.
Example Requests:
cURL for the schema index:
curl -H "Authorization: Bearer {YOUR ACCESS TOKEN}" https://us.api.concursolutions.com/receipts/schemas/
HTTPie for the schema index:
http https://us.api.concursolutions.com/receipts/schemas 'Authorization:Bearer {YOUR ACCESS TOKEN}'
cURL for a single schema:
curl -H "Authorization: Bearer {YOUR ACCESS TOKEN}" https://us.api.concursolutions.com/receipts/schemas/car-rental-receipt.schema.json
HTTPie for a single schema:
http https://us.api.concursolutions.com/receipts/schemas/car-rental-receipt.schema.json 'Authorization:Bearer {YOUR ACCESS TOKEN}'
Example Response:
{
"receiptSchemas": [
{
"rel": "http://schema.concursolutions.com/air-receipt.schema.json",
"method": "GET",
"href": "https://us.api.concursolutions.com/receipts/schemas/air-receipt.schema.json"
},
{
"rel": "http://schema.concursolutions.com/car-rental-receipt.schema.json",
"method": "GET",
"href": "https://us.api.concursolutions.com/receipts/schemas/car-rental-receipt.schema.json"
},
{
"rel": "http://schema.concursolutions.com/general-receipt.schema.json",
"method": "GET",
"href": "https://us.api.concursolutions.com/receipts/schemas/general-receipt.schema.json"
},
{
"rel": "http://schema.concursolutions.com/ground-transport-receipt.schema.json",
"method": "GET",
"href": "https://us.api.concursolutions.com/receipts/schemas/ground-transport-receipt.schema.json"
},
{
"rel": "http://schema.concursolutions.com/hotel-receipt.schema.json",
"method": "GET",
"href": "https://us.api.concursolutions.com/receipts/schemas/hotel-receipt.schema.json"
},
{
"rel": "http://schema.concursolutions.com/jpt-ic-card-receipt.schema.json",
"method": "GET",
"href": "https://us.api.concursolutions.com/receipts/schemas/jpt-ic-card-receipt.schema.json"
},
{
"rel": "http://schema.concursolutions.com/rail-receipt.schema.json",
"method": "GET",
"href": "https://us.api.concursolutions.com/receipts/schemas/rail-receipt.schema.json"
}
],
"supportingSchemas": [
{
"rel": "http://schema.concursolutions.com/address-original.schema.json",
"method": "GET",
"href": "https://us.api.concursolutions.com/receipts/schemas/address-original.schema.json"
},
{
"rel": "http://schema.concursolutions.com/address.schema.json",
"method": "GET",
"href": "https://us.api.concursolutions.com/receipts/schemas/address.schema.json"
},
{
"rel": "http://schema.concursolutions.com/common.schema.json",
"method": "GET",
"href": "https://us.api.concursolutions.com/receipts/schemas/common.schema.json"
},
{
"rel": "http://schema.concursolutions.com/discount.schema.json",
"method": "GET",
"href": "https://us.api.concursolutions.com/receipts/schemas/discount.schema.json"
},
{
"rel": "http://schema.concursolutions.com/line-item.schema.json",
"method": "GET",
"href": "https://us.api.concursolutions.com/receipts/schemas/line-item.schema.json"
},
{
"rel": "http://schema.concursolutions.com/location.schema.json",
"method": "GET",
"href": "https://us.api.concursolutions.com/receipts/schemas/location.schema.json"
},
{
"rel": "http://schema.concursolutions.com/merchant.schema.json",
"method": "GET",
"href": "https://us.api.concursolutions.com/receipts/schemas/merchant.schema.json"
},
{
"rel": "http://schema.concursolutions.com/payments.schema.json",
"method": "GET",
"href": "https://us.api.concursolutions.com/receipts/schemas/payments.schema.json"
},
{
"rel": "http://schema.concursolutions.com/receipt-core.schema.json",
"method": "GET",
"href": "https://us.api.concursolutions.com/receipts/schemas/receipt-core.schema.json"
},
{
"rel": "http://schema.concursolutions.com/taxes.schema.json",
"method": "GET",
"href": "https://us.api.concursolutions.com/receipts/schemas/taxes.schema.json"
}
]
}
Endpoint: Get Receipt Status
GET /v4/status/:receiptId
| Parameter | Requirement | Value |
|---|---|---|
| receiptId | required | The id of the receipt associated with the image. |
This endpoint may be used to see the current processing status of a receipt.
When a successful POST request is made the Link header of the response contains a 'processing-status' URL. This processing-status URL will be available for two weeks after the initial POST and will provide information regarding the processing status of your receipt.
There are four possible top level statuses: ACCEPTED, FAILED, PROCESSING, and PROCESSED.
In additional to a high level status, information will be provided in an array of event logs. Events that may be included in the logs will be typed as INFO, DEBUG, WARNING, or ERROR.
Example event messages:
| Type | Message |
|---|---|
| INFO | Receipt accepted. Queued for processing. |
| INFO | Initiated receipt processing. (event for each attempt) |
| ERROR | Error from User Profile service. Queued for reprocessing. |
| ERROR | Error from Imaging service. Queued for reprocessing. |
| ERROR | Error during image generation or retrieval. Queued for reprocessing. |
| INFO | Receipt image generated. |
| ERROR | Processing failed. |
| INFO | Processing finished. |
Example Requests:
cURL:
curl -H "Authorization: Bearer {YOUR ACCESS TOKEN}" https://us.api.concursolutions.com/receipts/v4/status/{RECEIPT ID}
HTTPie:
http https://us.api.concursolutions.com/receipts/v4/status/{RECEIPT ID} "Authorization: Bearer {YOUR ACCESS TOKEN}"
Example Response:
{
"status": "PROCESSED",
"logs": [
{
"logLevel": "INFO",
"message": "Receipt accepted. Queued for processing.",
"timestamp": "Mon, 08 May 2017 23:05:52 GMT"
},
{
"logLevel": "INFO",
"message": "Initiated receipt processing.",
"timestamp": "Mon, 08 May 2017 23:05:52 GMT"
},
{
"logLevel": "INFO",
"message": "Receipt image generated.",
"timestamp": "Mon, 08 May 2017 23:05:53 GMT"
},
{
"logLevel": "INFO",
"message": "Processing finished.",
"timestamp": "Mon, 08 May 2017 23:05:54 GMT"
}
]
}
Endpoint: Post a Receipt
POST /v4/users/:userId
| Parameter | Requirement | Value |
|---|---|---|
| userId | required | The id of the user to whom the receipt belongs. |
| receipt | required | The JSON receipt to be posted. |
| image | optional | Image of the receipt. If an image isn't provided, one will be generated automatically from the JSON. Refer to Supported Image Formats for more information. |
Creating a receipt requires JSON data about the transaction and, optionally, an image of the receipt. If an image is not supplied with the request, SAP Concur will automatically generate a receipt image based on the data provided. JSON schemas are used to validate the format of receipt data received in POST requests.
SAP Concur systems and clients rely on e-receipts to be legally valid tax documents in the relevant government jurisdictions. Please see this information regarding important usage restrictions.
Successful POST requests will receive a response of 201 Created. The Location header of the response contains a URL for your receipt. Once the receipt has been processed, it can be retrieved at this URL. The Link header of the response contains a processing-status URL for your receipt. More information can be found here.
Helpful Notes:
- Include link as a header and make its value: “
If you are not providing an image with your receipt data, the body of the request should be your receipt JSON.
Receipt images may be posted along with data. In this case, SAP Concur will use the provided image instead of generating a new one. To post data and an image, use multipart form data. The Content-Type:multipart/form-data header must be set. The image should be included under the key image, and the receipt JSON should be included under the key receipt. For information regarding image size, dimension, and type, please refer to Supported Image Formats.
Example Requests:
cURL data without image:
curl -v -X POST https://us.api.concursolutions.com/receipts/v4/users/{USER ID FROM YOUR ID TOKEN} \
-H "Authorization: Bearer {YOUR ACCESS TOKEN}" \
-H "Content-Type: application/json" \
-H "link: <http://schema.concursolutions.com/{VALIDATION SCHEMA FROM SCHEMA ENDPOINT}.schema.json>;rel=describedBy" \
-d @{PATH TO YOUR RECEIPT JSON}
cURL data and image:
curl -v -k -X POST https://us.api.concursolutions.com/receipts/v4/users/{USER ID FROM YOUR ID TOKEN} \
-H "Authorization: Bearer {YOUR ACCESS TOKEN}" \
-H "Content-Type:multipart/form-data" \
-H "link: <http://schema.concursolutions.com/{VALIDATION SCHEMA FROM SCHEMA ENDPOINT}.schema.json>;rel=describedBy" \
-F "receipt=<{PATH TO YOUR RECEIPT JSON};type=application/json" \
-F "image=@{PATH TO YOUR IMAGE};type={FILE MIME TYPE OF YOUR IMAGE}"
HTTPie data without image:
http POST https://us.api.concursolutions.com/receipts/v4/users/{USER ID FROM YOUR ID TOKEN} \
"Authorization:Bearer {YOUR ACCESS TOKEN}" \
"Content-Type: application/json" \
"link: <http://schema.concursolutions.com/{VALIDATION SCHEMA FROM SCHEMA ENDPOINT}.schema.json>;rel=describedBy" \
< {PATH TO YOUR RECEIPT JSON}
Example Response:
HTTP/1.1 201 Created
Link: <http://schema.concursolutions.com/car-rental-receipt.schema.json>; rel="describedBy", <https://us.api.concursolutions.com/receipts/v4/status/b0a4ab2bce8a49a08cf177cb997bf2ee>; rel="processing-status"
Location: https://us.api.concursolutions.com/receipts/v4/b0a4ab2bce8a49a08cf177cb997bf2ee
Content-Length: 0
Connection: keep-alive
Endpoint: Get a Receipt by ID
GET /v4/:receiptId
| Parameter | Requirement | Value |
|---|---|---|
| receiptId | required | The id of the receipt to be returned. |
Returns the JSON receipt associated with the ID in the URL.
Example Requests:
cURL:
curl -H "Authorization: Bearer {YOUR ACCESS TOKEN}" https://us.api.concursolutions.com/receipts/v4/{RECEIPT ID}
HTTPie:
http https://us.api.concursolutions.com/receipts/v4/{RECEIPT ID} "Authorization: Bearer {YOUR ACCESS TOKEN}"
Example Response
{
"dateTimeReceived": "2016-09-28T21:41:21.087Z",
"id": "85b76a2bf51a4ed7b8b252994d7d9e2b",
"image": "",
"receipt": {
...Receipt JSON...
},
"userId": "08bdda1e-0d4f-4261-9f1b-f9b8d9f817d6",
"validationSchema": "http://schema.concursolutions.com/car-rental-receipt.schema.json",
"self": "https://us.api.concursolutions.com/receipts/v4/85b76a2bf51a4ed7b8b252994d7d9e2b",
"template": "https://us.api.concursolutions.com/receipts/v4/{receiptId}"
}
Endpoint: Get Receipts By UserId
GET /v4/users/:userId
| Parameter | Requirement | Value |
|---|---|---|
| userId | required | The id of the user whose receipts will be returned. |
Returns all receipts for a given user ID.
Example Requests:
cURL:
curl -H "Authorization: Bearer {YOUR ACCESS TOKEN}" https://us.api.concursolutions.com/receipts/v4/users/{USER ID}
HTTPie:
http https://us.api.concursolutions.com/receipts/v4/users/{USER ID} "Authorization: Bearer {YOUR ACCESS TOKEN}"
Example Response:
{
"receipts": [
{
"dateTimeReceived": "2016-09-28T21:41:21.087Z",
"id": "85b76a2bf51a4ed7b8b252994d7d9e2b",
"image": "",
"receipt": {
...Receipt JSON...
},
"userId": "08bdda1e-0d4f-4261-9f1b-f9b8d9f817d6",
"validationSchema": "http://schema.concursolutions.com/car-rental-receipt.schema.json",
"self": "https://us.api.concursolutions.com/receipts/v4/85b76a2bf51a4ed7b8b252994d7d9e2b",
"template": "https://us.api.concursolutions.com/receipts/v4/{receiptId}"
},
{
"dateTimeReceived": "2016-09-28T19:59:30.488Z",
"id": "df8c1161d917439c9e6f141fd0d6b588",
"image": "",
"receipt": {
...Receipt JSON...
},
"userId": "08bdda1e-0d4f-4261-9f1b-f9b8d9f817d6",
"validationSchema": "http://schema.concursolutions.com/car-rental-receipt.schema.json",
"self": "https://us.api.concursolutions.com/receipts/v4/df8c1161d917439c9e6f141fd0d6b588",
"template": "https://us.api.concursolutions.com/receipts/v4/{receiptId}"
},
...
]
}
Endpoint: Get Receipt Image
GET /v4/:receiptId/image
| Parameter | Requirement | Value |
|---|---|---|
| receiptId | required | The id of the receipt associated with the image. |
If an image or PDF document was generated by or POSTed to Receipts v4, this endpoint can return the image in the same format that it was originally received by the API. Images for receipts created with v3 of the API are not accessible via this endpoint.
Example Requests:
cURL:
curl -H "Authorization: Bearer {YOUR ACCESS TOKEN}" https://us.api.concursolutions.com/receipts/v4/{RECEIPT ID}/image
HTTPie:
http https://us.api.concursolutions.com/receipts/v4/{RECEIPT ID}/image "Authorization: Bearer {YOUR ACCESS TOKEN}"
Image-Only Receipts
Note: This API is not designed to obtain the receipt images attached to an expense report. If you are an Enterprise Partner creating integrations that are intended to obtain final-approved Expense or Invoice data, and the accompanying receipt images that substantiate those transactions you will need to use Image v1. These scenarios include, but are not limited to: ERP integrations for financial journal entry postings, VAT reclaim integrations that obtain transactions to calculate VAT reclaim, project billing integrations used to substantiate expenses billed back, etc.
| Endpoint | Response Format | Request Summary |
|---|---|---|
| POST /v4/users/:userId/image-only-receipts | N/A | Post an image-only receipt |
| GET /v4/users/:userId/image-only-receipts | JSON | Get a user's image-only receipts |
| GET /v4/image-only-receipts/:receiptId | JSON | Get an image-only receipt by ID |
Endpoint: Post an Image-Only Receipt
POST /v4/users/:userId/image-only-receipts
| Parameter | Requirement | Value |
|---|---|---|
| userId | required | The id of the user to whom the receipt image belongs. |
| image | required | Image of the receipt. Refer to Supported Image Formats for more information. |
Successful POST requests will receive a response of 202 Accepted. The Location header of the response contains a URL for your receipt image. Once the receipt has been processed, it can be retrieved at this URL. The Link header of the response contains a processing-status URL for your receipt image.
Helpful Notes: - The header must include content-type with multipart/form-data as its value - In the body, add "image" as a key and select "file" from the dropdown since you will be linking an image file. Then, choose your saved image file as the value.
For information regarding image size, dimension, and type, please refer to Supported Image Formats.
Example Requests:
cURL:
curl -v -X POST https://us.api.concursolutions.com/receipts/v4/users/{USER ID FROM YOUR ID TOKEN}/image-only-receipts \
-H "Authorization: Bearer {YOUR ACCESS TOKEN}" \
-H "Content-Type:multipart/form-data" \
-F "image=@{PATH TO YOUR IMAGE};type=image/{FILE MIME TYPE OF YOUR IMAGE}"
Example Response:
HTTP/1.1 202 Accepted
Link: <https://us.api.concursolutions.com/receipts/v4/status/b0a4ab2bce8a49a08cf177cb997bf2ee>; rel="processing-status"
Location: https://us.api.concursolutions.com/receipts/v4/images/b0a4ab2bce8a49a08cf177cb997bf2ee
Content-Length: 0
Connection: keep-alive
Endpoint: Get Image-Only Receipts By UserId
GET /v4/users/:userId/image-only-receipts
| Parameter | Requirement | Value |
|---|---|---|
| userId | required | The id of the user whose receipt images will be returned. |
Returns the JSON metadata of receipt images for the user ID specified in the URL. Results should be paginated in the same manner as the e-receipt endpoint.
Example Requests:
cURL:
curl -H "Authorization: Bearer {YOUR ACCESS TOKEN}" https://us.api.concursolutions.com/receipts/v4/users/{USER ID}/image-only-receipts
HTTPie:
http https://us.api.concursolutions.com/receipts/v4/users/{USER ID}/image-only-receipts "Authorization: Bearer {YOUR ACCESS TOKEN}"
Example Response:
HTTP/1.1 200 OK
Content-Length: 800
Connection: keep-alive
{
"receiptsImages": [
{
"dateTimeReceived": "Wed May 24 2017 16:14:17 GMT+00:00",
"id": "a90fc48e0f0a44f2bd4838fd773b07a5",
"image": "https://us.api.concursolutions.com/receipts/v4/image-only-receipts/a90fc48e0f0a44f2bd4838fd773b07a5/image",
"userId": "abcd123456efg"
},
{ ... },
],
"next": "https://us.api.concursolutions.com/receipts/v4/users/abcd123456efg/image-only-receipts/page/1507587575592_d4721b2f3b304a9a9325fabdad5f50ad"
}
Endpoint: Get an Image-Only Receipt by ID
GET /v4/image-only-receipts/:receiptId
| Parameter | Requirement | Value |
|---|---|---|
| receiptId | required | The id of the receipt image to be returned. |
Returns the JSON metadata associated with the ID in the URL.
Example Requests:
cURL:
curl -v -X GET https://us.api.concursolutions.com/receipts/v4/image-only-receipts/{RECEIPT ID} \
-H "Authorization: Bearer {YOUR ACCESS TOKEN}"
HTTPie:
http https://us.api.concursolutions.com/receipts/v4/image-only-receipts/{RECEIPT ID} "Authorization: Bearer {YOUR ACCESS TOKEN}"
Example Response
HTTP/1.1 200 OK
Content-Length: 272
Connection: keep-alive
{
"dateTimeReceived": "Wed May 24 2017 16:14:17 GMT+00:00",
"id": "a90fc48e0f0a44f2bd4838fd773b07a5",
"image": "https://us.api.concursolutions.com/receipts/v4/image-only-receipts/a90fc48e0f0a44f2bd4838fd773b07a5/image",
"userId": "abcd123456efg"
}
Endpoint: Get Receipt Image (Image-Only)
GET /v4/image-only-receipts/:receiptId/image
| Parameter | Requirement | Value |
|---|---|---|
| receiptId | required | The id of the receipt image to be returned. |
Returns the image in the same format that it was originally received by the API (image/png, image/jpg, image/jpeg, image/tiff, image/tif, image/gif, or application/pdf).
Example Requests:
cURL:
curl -H "Authorization: Bearer {YOUR ACCESS TOKEN}" https://us.api.concursolutions.com/receipts/v4/image-only-receipts/{RECEIPT ID}/image
HTTPie:
http https://us.api.concursolutions.com/receipts/v4/image-only-receipts/{RECEIPT ID}/image "Authorization: Bearer {YOUR ACCESS TOKEN}"
Supported Receipt Types
Receipts can be any of the following types
See the schema documentation below for the specifications of each type, plus the various schemas that are shared components of each receipt schema. Property names mentioned in bold italics are required fields.
Schemas
Address
| Property Name | Type | Format | Description |
|---|---|---|---|
| streetAddress | string | N/A | |
| addressLocality | string | N/A | City |
| addressRegion | string | ^[a-zA-Z0-9]{1,3}$ | 1 to 3 character country subdivision code as defined in ISO 3166-2:2013 |
| addressCountry | string | country-code | 2 or 3 character country code as defined in ISO 3166-1:2013 |
| postalCode | string | N/A |
Air Receipt
Schema for airline receipts. * Includes all of Receipt Core Definitions
| Property Name | Type | Format | Description |
|---|---|---|---|
| itineraryLocator | string | ^(?!\s*$).+ | Unique ID of an itinerary (also know as a trip) in Concur’s Itinerary Service. An itinerary can contain one or more bookings from various sources. |
| tickets | array | tickets | Air tickets issued. |
| lineItems | array | lineItems | Ancillary airline fees. |
tickets
| Property Name | Type | Format | Description |
|---|---|---|---|
| number | string | N/A | Ticket number issued by the airline when the payment is made. Ticket numbers are globally unique for all IATA carriers. The first 3 digits identify the airline. The three digit code for each airline can be found here. For example the ticket number for American Airlines where 001 is the airline: 0012375432602. |
| recordLocator | string | N/A | Confirmation identifier for the ticket created by the airline. For most airlines this is a 6 character alphanumeric code that is unique for a short period of time and could be reused in the future. |
| issueDateTime | string | date-time | Date and time the ticket was issued. |
| pseudoCityCode | string | ^[a-zA-Z]{3}$ | IATA city code the ticket was issued from. For example, SEA for Seattle. |
| IATAAgencyNumber | string | ^[0-9]{8}$ | Identifying number assigned by the IATA to the agency issuing the ticket. |
| agencyName | string | N/A | Name of the agency issuing the ticket. |
| passengerName | string | N/A | Name of the passenger associated with the ticket. |
| coupons | array | coupons | Flights issued within this transaction. |
coupons
| Property Name | Type | Format | Description |
|---|---|---|---|
| originationAirportIATACode | string | ^[a-zA-Z]{3}$ | IATA airport code of the flight’s origin. |
| originationDateTime | string | date-time | Date and time of origin. |
| destinationAirportIATACode | string | ^[a-zA-Z]{3}$ | IATA airport code of the flight’s destination. |
| destinationDateTime | string | date-time | Date and time of destination. |
| flightNumber | string | N/A | Flight identifier. |
| couponNumber | string | ^(?!\s*$).+ | Identifier associated with the given coupon. |
| operatingAirlineCode | string | ^[a-zA-Z]{2}$ | IATA code of the airline operating the flight. |
| marketingCarrier | string | ^[a-zA-Z0-9]{3,8}$ | Flight designator booking the flight. |
| operatingCarrier | string | ^[a-zA-Z0-9]{3,8}$ | Flight designator operating the flight. |
| classOfServiceCode | string | ^[a-zA-Z]$ | Class of service per the airline’s class of service codes. Most airlines use the same codes but some airlines have custom codes. |
| fareBasisCode | string | ^[a-zA-Z0-9]{2,8}$ | Rate code the airline used to calculate the fare for this flight. |
| ticketDesignatorCode | string | ^[a-zA-Z0-9*?]{1,10}$ | A valid ticket designator code to indicate what type of discount is applied, such as for a child or infant, or airline employee. This is a 1 to 10 alphanumeric code and can optionally include a single asterisk. Ticket designators are free-form text codes which help identify ticket types. Airlines determine which ticket designators they will use as no standards currently exist. |
| fare | string | ^[-]?\d*.?\d+$ | Fare charged for the flight. |
| taxes | array | Taxes | Schema for objects that make up an array of taxes. Used in most receipt types. |
| lineItems | array | lineItems | Line Items/fees specific to a leg of the trip. Eg. Baggage fees, class of service fees, priority boarding, meals. |
Definitions
| Property Name | Type | Format | Description |
|---|---|---|---|
| IATAAirportCode | string | ^[a-zA-Z]{3}$ | 3-letter IATA code for an airport. |
| IATAAirlineCode | string | ^[a-zA-Z]{2}$ | 2-letter code for an airline. |
| IATACityCode | string | ^[a-zA-Z]{3}$ | 3-letter IATA city code. For example, SEA for Seattle. |
| IATAAgencyNumber | string | ^[0-9]{8}$ | 8-character ID number assigned by the IATA to an agency. |
| flightDesignator | string | ^[a-zA-Z0-9]{3,8}$ | |
| classOfServiceCode | string | ^[a-zA-Z]$ | |
| fareBasisCode | string | ^[a-zA-Z0-9]{2,8}$ | |
| ticketDesignatorCode | string | ^[a-zA-Z0-9*?]{1,10}$ |
Car Rental Receipt
Schema for car rentals. This does not include ride services or taxis. * Includes all of Receipt Core Definitions
| Property Name | Type | Format | Description |
|---|---|---|---|
| itineraryLocator | string | ^(?!\s*$).+ | Unique ID of an itinerary (also know as a trip) in Concur’s Itinerary Service. An itinerary can contain one or more bookings from various sources. |
| segmentLocator | string | ^(?!\s*$).+ | Unique ID of a single travel event in Concur’s Itinerary Service. An itinerary can contain one or more bookings and each booking can contain one or more segments. The segmentLocator uniquely identifies an event like a car rental with a specific start and end date or a single air segment/sector. |
| startDateTime | string | date-time | A subset of ISO 8601 date-times. The first restriction is that the dateTime requires a date, a time (at least the hour portion), and a UTC offset. The second restriction is that the dateTime does not allow a time to be formatted in UTC time (2015-11-02T14:30Z - notice the Z) without an offset; this is because it would be impossible for us to know the original offset so we could not generate a receipt with the correct local time. |
| endDateTime | string | date-time | A subset of ISO 8601 date-times. The first restriction is that the dateTime requires a date, a time (at least the hour portion), and a UTC offset. The second restriction is that the dateTime does not allow a time to be formatted in UTC time (2015-11-02T14:30Z - notice the Z) without an offset; this is because it would be impossible for us to know the original offset so we could not generate a receipt with the correct local time. |
| pickupLocation | object | Location | Schema representing a location, including geographical information and a postal address. Used in multiple receipt types. |
| dropoffLocation | object | Location | Schema representing a location, including geographical information and a postal address. Used in multiple receipt types. |
| rentalDays | integer | N/A | Total number of days for which the car was rented. |
| rentalAgreementNumber | string | N/A | Agreement identifier. |
| confirmationNumber | string | N/A | Booking confirmation identifier. |
| vehicle | object | vehicle | |
| driverName | string | N/A | Name of the driver/renter of the vehicle. |
| distance | object | distance | Distance traveled. |
| odometerReadingOut | number | N/A | Odometer reading at the start of the rental period. A number with up to one decimal place is expected. |
| odometerReadingIn | number | N/A | Odometer reading at the end of the rental period. A number with up to one decimal place is expected. |
| additionalDriver | boolean | N/A | Additional approved driver (true) or not (false). |
| lineItems | array | lineItems | Break down of all car rental charges. This could include daily rate, fees, insurance, GPS rental and other add-ons. |
vehicle
| Property Name | Type | Format | Description |
|---|---|---|---|
| registrationNumber | string | N/A | Registration or license plate identifier. |
| description | string | N/A | Vehicle description, including year, make and model. |
| classReservedCode | string | ^[a-zA-Z]{4}$ | Four-letter Association of Car Rental Industry Systems Standard (ACRISS) car code. |
| classRentedCode | string | ^[a-zA-Z]{4}$ | Actual vehicle rented ACRISS identifier. |
| classChargedCode | string | ^[a-zA-Z]{4}$ | Car class code actually charged to the user. |
| engineSize | string | ^[0-9]{1,4}$ | Engine displacement in cubic centimeters. |
Definitions
| Property Name | Type | Format | Description |
|---|---|---|---|
| acrissCarCode | string | ^[a-zA-Z]{4}$ | Four-letter Association of Car Rental Industry Systems Standard (ACRISS) car code. |
| engineSize | string | ^[0-9]{1,4}$ | Engine displacement in cubic centimeters. |
Common Definitions
Shared definitions that are utilized in multiple receipt types.
Definitions
| Property Name | Type | Format | Description |
|---|---|---|---|
| dateTime | string | date-time | The dateTime validation validates for a subset of ISO 8601 date-times. The first restriction is that the dateTime requires a date, a time (at least the hour portion), and a UTC offset. The second restriction is that the dateTime does not allow a time to be formatted in UTC time (2015-11-02T14:30Z - notice the Z) without an offset; This is because it would be impossible for us to know the original offset so we could not generate a receipt with the correct local time. |
| duration | string | ^(-)?P(?:(-?[0-9,.])Y)?(?:(-?[0-9,.])M)?(?:(-?[0-9,.])W)?(?:(-?[0-9,.])D)?(?:T(?:(-?[0-9,.])H)?(?:(-?[0-9,.])M)?(?:(-?[0-9,.]*)S)?)?$ | Duration of a time interval as defined in ISO 8601 |
| nonEmptyString | string | ^(?!\s*$).+ | Non-empty string. Length must be at least 1 character. |
| addressRegion | string | ^[a-zA-Z0-9]{1,3}$ | 1 to 3 character country subdivision code as defined in ISO 3166-2:2013 |
| addressCountry | string | country-code | 2 or 3 character country code as defined in ISO 3166-1:2013 |
| currency | string | ^[-]?\d*.?\d+$ | String representing an amount of money. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt. |
| currencyCode | string | currency-code | 3-letter currency code as defined in ISO 4217 |
| latitude | number | N/A | Numeric latitude value between -90 and 90 |
| longitude | number | N/A | Numeric longitude value between -180 and 180 |
| positiveInteger | integer | N/A | Positive integer value of at least 1 |
| positiveNumber | number | N/A | Positive number value of at least 0 |
| negativeCurrency | string | ^[-]\d*.?\d+$ | String representing a negative amount of money, normally used for a discount. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt. |
distance
| Property Name | Type | Format | Description |
|---|---|---|---|
| totalDistance | number | N/A | |
| unit | N/A | N/A | Can be any of the following values: mi, km |
Discount
Schema for discounts, such as coupons or discount codes, that could be part of a transaction.
| Property Name | Type | Format | Description |
|---|---|---|---|
| discountName | string | N/A | The name of the discount. |
| discountCode | string | N/A | The code for the discount. |
| discountRate | string | N/A | The percentage of discount provided. |
| discountAmount | string | ^[-]\d*.?\d+$ | String representing a negative amount of money, normally used for a discount. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt. |
General Receipt
General receipt type for transactions that do not fall under one of the more specific receipt types. This might include retail stores or restaurants. * Includes all of Receipt Core Definitions
| Property Name | Type | Format | Description |
|---|---|---|---|
| lineItems | array | lineItems | Line items specified for general receipts. |
Ground Transport Receipt
Schema for ground transportation receipts. This includes essentially all forms of non-aerial transportation, except those that run on railed tracks. * Includes all of Receipt Core Definitions
| Property Name | Type | Format | Description |
|---|---|---|---|
| itineraryLocator | string | ^(?!\s*$).+ | Non-empty string. Length must be at least 1 character. |
| segmentLocator | string | ^(?!\s*$).+ | Non-empty string. Length must be at least 1 character. |
| classOfService | string | ^(?!\s*$).+ | Non-empty string. Length must be at least 1 character. |
| startDateTime | string | date-time | A subset of ISO 8601 date-times. The first restriction is that the dateTime requires a date, a time (at least the hour portion), and a UTC offset. The second restriction is that the dateTime does not allow a time to be formatted in UTC time (2015-11-02T14:30Z - notice the Z) without an offset; this is because it would be impossible for us to know the original offset so we could not generate a receipt with the correct local time. |
| endDateTime | string | date-time | A subset of ISO 8601 date-times. The first restriction is that the dateTime requires a date, a time (at least the hour portion), and a UTC offset. The second restriction is that the dateTime does not allow a time to be formatted in UTC time (2015-11-02T14:30Z - notice the Z) without an offset; this is because it would be impossible for us to know the original offset so we could not generate a receipt with the correct local time. |
| travelDuration | string | ^(-)?P(?:(-?[0-9,.])Y)?(?:(-?[0-9,.])M)?(?:(-?[0-9,.])W)?(?:(-?[0-9,.])D)?(?:T(?:(-?[0-9,.])H)?(?:(-?[0-9,.])M)?(?:(-?[0-9,.]*)S)?)?$ | Duration of a time interval as defined in ISO 8601 |
| mapUrl | string | Google Maps URI Pattern | Link to an image of the traveled route. |
| pickupLocation | object | Location | Schema representing a location, including geographical information and a postal address. Used in multiple receipt types. |
| dropoffLocation | object | Location | Schema representing a location, including geographical information and a postal address. Used in multiple receipt types. |
| distance | object | distance | Object representing a distance. |
| driverNumber | string | N/A | Unique identifier assigned by the ride company to a driver. |
| lineItems | array | lineItems | Descriptive breakdown of the fare charged. For example: base fare, distance travelled, discount and other add-ons. |
Google Maps URI Pattern: ^https://(www|maps).(googleapis|google).[a-z]+/maps/
Hotel Receipt
Schema for hotel receipts. * Includes all of Receipt Core Definitions
| Property Name | Type | Format | Description |
|---|---|---|---|
| itineraryLocator | string | ^(?!\s*$).+ | Unique ID of an itinerary (also know as a trip) in Concur’s Itinerary Service. An itinerary can contain one or more bookings from various sources. |
| segmentLocator | string | ^(?!\s*$).+ | Unique ID of a single travel event in Concur’s Itinerary Service. An itinerary can contain one or more bookings and each booking can contain one or more segments. The segmentLocator uniquely identifies an event like a car rental with a specific start and end date or a single air segment/sector. |
| property | object | Location | Physical property location information for the hotel property. This is often different than the merchant location information. |
| confirmationNumber | string | N/A | Booking identifier. |
| checkInDateTime | string | date-time | A subset of ISO 8601 date-times. The first restriction is that the dateTime requires a date, a time (at least the hour portion), and a UTC offset. The second restriction is that the dateTime does not allow a time to be formatted in UTC time (2015-11-02T14:30Z - notice the Z) without an offset; this is because it would be impossible for us to know the original offset so we could not generate a receipt with the correct local time. |
| checkOutDateTime | string | date-time | A subset of ISO 8601 date-times. The first restriction is that the dateTime requires a date, a time (at least the hour portion), and a UTC offset. The second restriction is that the dateTime does not allow a time to be formatted in UTC time (2015-11-02T14:30Z - notice the Z) without an offset; this is because it would be impossible for us to know the original offset so we could not generate a receipt with the correct local time. |
| guests | array | guests | Guest information. |
| numberInParty | integer | N/A | Number of individuals for the stay. |
| room | object | room | |
| nightsStayed | integer | N/A | Positive integer value of at least 1 |
| lineItems | array | lineItems |
guests
| Property Name | Type | Format | Description |
|---|---|---|---|
| guestNameRecord | string | N/A | The loyalty or membership number of the hotel guest. |
| firstName | string | ^(?!\s*$).+ | Non-empty string. Length must be at least 1 character. |
| lastName | string | ^(?!\s*$).+ | Non-empty string. Length must be at least 1 character. |
| address | object | Address | Address of the guest. It is highly recommended that the business address of the guest is provided if the hotel is provided with one. Doing so will help VAT reclamation partners who work with companies, to have compliant receipts accepted by the tax authority when filing tax reclaims. |
property
| Property Name | Type | Format | Description |
|---|---|---|---|
| name | string | N/A | The name for the location. |
| number | string | N/A | The identifier the company assigned to this location. |
| latitude | number | N/A | Numeric latitude value between -90 and 90 |
| longitude | number | N/A | Numeric longitude value between -180 and 180 |
| internetAddress | string | N/A | |
| emailAddress | string | N/A | |
| telephoneNumber | string | N/A | |
| faxNumber | string | N/A | |
| address | object | Address | Common address object used by all receipt types except for the JPT IC Card receipt, which uses Address-Original. |
room
| Property Name | Type | Format | Description |
|---|---|---|---|
| roomNumber | string | N/A | Room number where the guest stayed. |
| roomType | string | N/A | Type of room where the guest stayed. For example, Standard, Deluxe, etc. |
| ratePlanType | string | N/A | Name of the rate plan according to which the guest was charged. |
| averageDailyRoomRate | string | ^[-]?\d*.?\d+$ | Average of the daily room rates for the duration of the guests stay. Room rates usually differ from day to day. |
segments
| Property Name | Type | Format | Description |
|---|---|---|---|
| sequenceNumber | integer | N/A | Unique transaction identifier for every trip taken using the IC card. |
| dateTime | string | date-time | A subset of ISO 8601 date-times. The first restriction is that the dateTime requires a date, a time (at least the hour portion), and a UTC offset. The second restriction is that the dateTime does not allow a time to be formatted in UTC time (2015-11-02T14:30Z - notice the Z) without an offset; this is because it would be impossible for us to know the original offset so we could not generate a receipt with the correct local time. |
| fromStationCode | string | N/A | Departure station code of the route. This code is specified to the IC Card vendor. Concur Expense has a transcoding table to Expense location codes. |
| fromStationName | string | N/A | Departure station label of the route. |
| toStationCode | string | N/A | Arrival station code of the route. This code is specified to the IC Card vendor. Concur Expense has a transcoding table to Expense location codes. |
| toStationName | string | N/A | Arrival station label of the route. |
| fromIsCommuterPass | boolean | N/A | Whether or not the departure route is included in the commuter pass subscription of the employee. |
| toIsCommuterPass | boolean | N/A | Whether or not the arrival route is included in the commuter pass subscription of the employee. |
| distance | number | N/A | Positive number value of at least value as 0 |
icCardSegment
| Property Name | Type | Format | Description |
|---|---|---|---|
| sequenceNumber | integer | N/A | Unique transaction identifier for every trip taken using the IC card. |
| dateTime | string | date-time | Transaction date and time. |
| fromStationCode | string | N/A | Departure station code of the route. This code is specified to the IC Card vendor. Concur Expense has a transcoding table to Expense location codes. |
| fromStationName | string | N/A | Departure station label of the route. |
| toStationCode | string | N/A | Arrival station code of the route. This code is specified to the IC Card vendor. Concur Expense has a transcoding table to Expense location codes. |
| toStationName | string | N/A | Arrival station label of the route. |
| fromIsCommuterPass | boolean | N/A | Whether or not the departure route is included in the commuter pass subscription of the employee. |
| toIsCommuterPass | boolean | N/A | Whether or not the arrival route is included in the commuter pass subscription of the employee. |
| distance | number | N/A | Positive number value of at least value as 0 |
Line Item
Generic line item. These objects are included in arrays in most receipt types.
| Property Name | Type | Format | Description |
|---|---|---|---|
| sequenceNumber | integer | N/A | The order in which the item appears in the sequence of line items when the receipt is rendered by Concur. |
| dateTime | string | date-time | A subset of ISO 8601 date-times. The first restriction is that the dateTime requires a date, a time (at least the hour portion), and a UTC offset. The second restriction is that the dateTime does not allow a time to be formatted in UTC time (2015-11-02T14:30Z - notice the Z) without an offset; this is because it would be impossible for us to know the original offset so we could not generate a receipt with the correct local time. |
| reference | string | N/A | The item SKU, identifier or some other attribute the merchant uses to reference the item. |
| description | string | ^(?!\s*$).+ | Non-empty string. Length must be at least 1 character. |
| additionalDescription | string | N/A | |
| semanticsCode | string | ^(?!\s*$).+ | The Concur semantics code for the line item. |
| unitCost | string | ^[-]?\d*.?\d+$ | Amount per unit. |
| quantity | integer | N/A | |
| total | string | ^[-]?\d*.?\d+$ | String representing an amount of money. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt. |
| subtotal | string | ^[-]?\d*.?\d+$ | String representing an amount of money. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt. |
| taxesTotal | string | ^[-]?\d*.?\d+$ | String representing an amount of money. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt. |
| taxes | array | Taxes | Schema for objects that make up an array of taxes. Used in most receipt types. |
| vatApplicable | boolean | N/A | If the line item was subject to a value added tax then true, if not then false. |
| amountIncludesVat | boolean | N/A | |
| discounts | array | discounts | The discounts offered for this line item. |
Location
Schema representing a location, including geographical information and a postal address. Used in multiple receipt types.
| Property Name | Type | Format | Description |
|---|---|---|---|
| name | string | N/A | The name for the location. |
| number | string | N/A | The identifier the company assigned to this location. |
| latitude | number | N/A | Numeric latitude value between -90 and 90 |
| longitude | number | N/A | Numeric longitude value between -180 and 180 |
| internetAddress | string | N/A | |
| emailAddress | string | N/A | |
| telephoneNumber | string | N/A | |
| faxNumber | string | N/A | |
| address | object | Address | Common address object used by all receipt types except for the JPT IC Card receipt, which uses Address-Original. |
Merchant
Schema for an object representing a merchant. The broker and seller properties in all receipts use this schema.
| Property Name | Type | Format | Description |
|---|---|---|---|
| name | string | ^(?!\s*$).+ | Non-empty string. Length must be at least 1 character. |
| description | string | N/A | Description of the service provided by the merchant. |
| taxId | string | N/A | The tax identification number assigned to the merchant by the national tax authority. If the partner is providing a tax invoice, then providing a tax identification number is recommended. |
| location | object | Location | Schema representing a location, including geographical information and a postal address. Used in multiple receipt types. |
Payments
The payments array allows for one or more payment methods used in the transaction to be defined. All payment methods defined within the array result in the value for total in the base object of the receipt. The JSON keyword ‘anyOf’ indicates at least one of the following is required and multiple can be present: cash, creditCard, companyPaid, digitalWallet and / or unusedTicket.
cash
| Property Name | Type | Format | Description |
|---|---|---|---|
| amount | string | ^[-]?\d*.?\d+$ | String representing an amount of money. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt. |
creditCard
| Property Name | Type | Format | Description |
|---|---|---|---|
| amount | string | ^[-]?\d*.?\d+$ | String representing an amount of money. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt. |
| cardDetail | object | cardDetail | Credit card information. |
cardDetail
| Property Name | Type | Format | Description |
|---|---|---|---|
| cardType | N/A | N/A | Can be any of the following values: American Express, Diners Club, Discover, MasterCard, Visa, Carte Blanche, Enroute, Universal Air Travel, JCB, EuroCard |
| creditCardId | string | ^[0-9]{4}$ | Last four digits of the credit card number to meet FACTA and PCI requirements |
| authorizationCode | string | N/A | Authorization code for transaction. |
companyPaid
| Property Name | Type | Format | Description |
|---|---|---|---|
| source | N/A | N/A | Can be any of the following values: GhostCard, LodgeCard, DirectPay, Invoice |
| amount | string | ^[-]?\d*.?\d+$ | String representing an amount of money. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt. |
| cardDetail | object | cardDetail | Credit card information. |
cardDetail
| Property Name | Type | Format | Description |
|---|---|---|---|
| cardType | N/A | N/A | Can be any of the following values: American Express, Diners Club, Discover, MasterCard, Visa, Carte Blanche, Enroute, Universal Air Travel, JCB, EuroCard |
| creditCardId | string | ^[0-9]{4}$ | Last four digits of the credit card number to meet FACTA and PCI requirements |
| authorizationCode | string | N/A | Authorization code for transaction. |
digitalWallet
| Property Name | Type | Format | Description |
|---|---|---|---|
| source | N/A | N/A | Can be any of the following values: ApplePay, AndroidPay, SamsungPay, PayPal, OlaMoney |
| amount | string | ^[-]?\d*.?\d+$ | String representing an amount of money. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt. |
unusedTicket
| Property Name | Type | Format | Description |
|---|---|---|---|
| ticketNumber | string | ^(?!\s*$).+ | Non-empty string. Length must be at least 1 character. |
| amount | string | ^[-]?\d*.?\d+$ | String representing an amount of money. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt. |
cardDetail
| Property Name | Type | Format | Description |
|---|---|---|---|
| cardType | N/A | N/A | Can be any of the following values: American Express, Diners Club, Discover, MasterCard, Visa, Carte Blanche, Enroute, Universal Air Travel, JCB, EuroCard |
| creditCardId | string | ^[0-9]{4}$ | Last four digits of the credit card number to meet FACTA and PCI requirements |
| authorizationCode | string | N/A | Authorization code for transaction. |
Rail Receipt
Schema for rail or train receipts. * Includes all of Receipt Core Definitions
| Property Name | Type | Format | Description |
|---|---|---|---|
| itineraryLocator | string | ^(?!\s*$).+ | Unique ID of an itinerary (also know as a trip) in Concur’s Itinerary Service. An itinerary can contain one or more bookings from various sources. |
| lineItems | array | lineItems | Break down of all charges which could include insurance purchased for all train tickets, paid wi-fi etc. |
| railTickets | array | railTickets |
railTickets
| Property Name | Type | Format | Description |
|---|---|---|---|
| ticketNumber | string | N/A | |
| recordLocator | string | N/A | Confirmation identifier for the ticket. This code is usually unique for a short period of time and could be reused by the rail company in the future. |
| issueDateTime | string | date-time | Date and time the ticket was issued. |
| passengerName | string | N/A | Name of the person associated withthe ticket. |
| fare | string | ^[-]?\d*.?\d+$ | Fare charged for a train ticket. This will be the total of all segments in this train ticket. |
| segments | array | segments | Segments for this train ticket. |
segments
| Property Name | Type | Format | Description |
|---|---|---|---|
| departureStation | string | N/A | Name of the station from which the train is departing. |
| departureDateTime | string | date-time | A subset of ISO 8601 date-times. The first restriction is that the dateTime requires a date, a time (at least the hour portion), and a UTC offset. The second restriction is that the dateTime does not allow a time to be formatted in UTC time (2015-11-02T14:30Z - notice the Z) without an offset; this is because it would be impossible for us to know the original offset so we could not generate a receipt with the correct local time. |
| arrivalStation | string | N/A | Name of the station where the train is arriving. |
| arrivalDateTime | string | date-time | A subset of ISO 8601 date-times. The first restriction is that the dateTime requires a date, a time (at least the hour portion), and a UTC offset. The second restriction is that the dateTime does not allow a time to be formatted in UTC time (2015-11-02T14:30Z - notice the Z) without an offset; this is because it would be impossible for us to know the original offset so we could not generate a receipt with the correct local time. |
| trainNumber | string | N/A | Train identifier |
| trainType | string | N/A | Type of train. For example TGV or TER in France. |
| classOfServiceCode | string | ^(?!\s*$).+ | The class of travel. |
| fare | string | ^[-]?\d*.?\d+$ | Fare charged for this segment of the train ride. |
| taxes | array | Taxes | Taxes paid for this segment. |
| lineItems | array | lineItems | Line items specific to this segment. This could include meals, seat reservations, insurance etc. |
Receipt Core Definitions
Core values for all receipt types. All major receipt schemas include these core objects.
| Property Name | Type | Format | Description |
|---|---|---|---|
| dateTime | string | date-time | Date and time of the transaction. |
| total | string | ^[-]?\d*.?\d+$ | The total amount of the transaction including all lineitems and taxes. |
| subtotal | string | ^[-]?\d*.?\d+$ | The amount in the transaction excluding taxes. |
| taxesTotal | string | ^[-]?\d*.?\d+$ | The amount of tax paid in the transaction. |
| discountsTotal | string | ^[-]\d*.?\d+$ | String representing a negative amount of money, normally used for a discount. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt. |
| currencyCode | string | currency-code | Currency paid to the merchant. |
| broker | object | Merchant | The entity that facilitates the transaction between the seller and end user. |
| seller | object | Merchant | The entity providing service to the end user. |
| payments | array | Payments | |
| discounts | array | discounts | The discounts offered on this transaction. |
| taxes | array | Taxes | Taxes paid as part of transaction. |
| reference | string | N/A | The unique receipt provider or merchant identifier for this receipt or invoice. This value can also be referred to as transaction number, check number, order ID or similar. |
| collectionReference | string | N/A | Use this key to group related receipts into a collection for credits, tips or other adjustments to the original transaction and looking at groups of receipts for analysis purposes. The reference and collectionReference keys typically have separate and unique values but could be the same for the first receipt in a collection. |
| taxInvoice | boolean | N/A | A tax invoice (true) or otherwise (false). |
broker
| Property Name | Type | Format | Description |
|---|---|---|---|
| name | string | ^(?!\s*$).+ | Non-empty string. Length must be at least 1 character. |
| description | string | N/A | Description of the service provided by the merchant. |
| taxId | string | N/A | The tax identification number assigned to the merchant by the national tax authority. If the partner is providing a tax invoice, then providing a tax identification number is recommended. |
| location | object | Location | Schema representing a location, including geographical information and a postal address. Used in multiple receipt types. |
seller
| Property Name | Type | Format | Description |
|---|---|---|---|
| name | string | ^(?!\s*$).+ | Non-empty string. Length must be at least 1 character. |
| description | string | N/A | Description of the service provided by the merchant. |
| taxId | string | N/A | The tax identification number assigned to the merchant by the national tax authority. If the partner is providing a tax invoice, then providing a tax identification number is recommended. |
| location | object | Location | Schema representing a location, including geographical information and a postal address. Used in multiple receipt types. |
Taxes
Schema for objects that make up an array of taxes. Used in most receipt types.
| Property Name | Type | Format | Description |
|---|---|---|---|
| authority | object | authority | The country or subdivision that charged the tax as per ISO 3166-2:2013. |
| name | string | N/A | |
| rate | number | N/A | |
| rateType | string | N/A | The rate type for the tax charged. For value added tax this could be Zero, Standard, Reduced, etc. |
| amount | string | ^[-]?\d*.?\d+$ | String representing an amount of money. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt. |
authority
| Property Name | Type | Format | Description |
|---|---|---|---|
| addressCountry | string | country-code | 2 or 3 character country code as defined in ISO 3166-1:2013 |
| addressRegion | string | ^[a-zA-Z0-9]{1,3}$ | 1 to 3 character country subdivision code as defined in ISO 3166-2:2013 |
Sample Receipts
Below we have sample receipt data and the corresponding receipt images for the following receipt types:
Air (Multiple Tickets)
Receipt Data
{
"taxInvoice": true,
"reference": "ABCD1234",
"dateTime": "2099-11-10T16:04:49-0700",
"total": "1400.40",
"taxesTotal": "123.38",
"subtotal": "1277.02",
"currencyCode": "USD",
"broker": {
"name": "ACME Corporation",
"description": "",
"taxId": "123-21213",
"location": {
"name": "Headquarters",
"number": "",
"latitude": 41.8819,
"longitude": -87.6278,
"internetAddress": "http://www.acmecorporation.com",
"emailAddress": "info@acmecorporation.com",
"telephoneNumber": "1-877-555-5555",
"faxNumber": "",
"address": {
"streetAddress": "333 108th Ave NE",
"addressLocality": "Bellevue",
"addressRegion": "WA",
"addressCountry": "US",
"postalCode": "98004"
}
}
},
"seller": {
"name": "ACME Airlines",
"description": "",
"taxId": "867-53090",
"location": {
"name": "Headquarters",
"number": "",
"latitude": 37.2714,
"longitude": -85.3262,
"internetAddress": "http://www.acmeairlines.com",
"emailAddress": "contact@acmeairlines.com",
"telephoneNumber": "1-888-555-5555",
"faxNumber": "",
"address": {
"streetAddress": "1 Ground Transport Way",
"addressLocality": "Seattle",
"addressRegion": "WA",
"addressCountry": "US",
"postalCode": "90001"
}
}
},
"taxes": [
{
"authority": {
"addressCountry": "US",
"addressRegion": "WA"
},
"name": "Transportation Tax",
"rate": 7.50,
"amount": "91.38"
},
{
"authority": {
"addressCountry": "US"
},
"name": "United States - Flight Segment Tax",
"rate": 10.0,
"amount": "32.00"
}
],
"payments": [
{
"amount": "1400.40",
"cardDetail": {
"cardType": "Visa",
"creditCardId": "7423",
"authorizationCode": "AB123654789"
}
}
],
"itineraryLocator": "1122337694093",
"tickets": [
{
"number": "0062698215636",
"recordLocator": "CU9GEF",
"issueDateTime": "2015-11-29T19:15:55-0700",
"pseudoCityCode": "SEA",
"IATAAgencyNumber": "87654321",
"agencyName": "ACME Airlines",
"passengerName": "Jimmy Dean",
"fare": "609.31",
"coupons": [
{
"originationAirportIATACode": "SEA",
"originationDateTime": "2015-12-25T09:00:00-0700",
"destinationAirportIATACode": "MSP",
"destinationDateTime": "2015-12-25T14:14:00-0500",
"flightNumber": "DL 1768",
"couponNumber": "D167693",
"operatingAirlineCode": "DL",
"marketingCarrier": "DL1768",
"operatingCarrier": "DL1768",
"classOfServiceCode": "T",
"fareBasisCode": "YHRT15",
"ticketDesignatorCode": "FSG*SFR",
"fare": "152.33",
"taxes": [
{
"authority": {
"addressCountry": "US"
},
"name": "Transportation Tax",
"rate": 7.50,
"amount": "11.42"
}
],
"lineItems": [
{
"sequenceNumber": 1,
"description": "United States - September 11th Security Fee",
"additionalDescription": "Passenger Civil Aviation Security Service Fee",
"semanticsCode": "OTHER",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "2.80"
},
{
"sequenceNumber": 2,
"description": "United States - Passenger Facility Charge",
"additionalDescription": "",
"semanticsCode": "SEGFEE_AS_FEE",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "4.50"
},
{
"sequenceNumber": 3,
"description": "United States - Flight Segment Tax",
"additionalDescription": "",
"semanticsCode": "SEGFEE_AS_TAX",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "4.00"
}
]
},
{
"originationAirportIATACode": "MSP",
"originationDateTime": "2015-12-25T15:25:00-0500",
"destinationAirportIATACode": "GFK",
"destinationDateTime": "2015-12-25T16:50:00-0500",
"flightNumber": "OO 4656",
"couponNumber": "D187322",
"operatingAirlineCode": "DL",
"marketingCarrier": "DL1768Z",
"operatingCarrier": "OO4656B",
"classOfServiceCode": "T",
"fareBasisCode": "YAD1234",
"ticketDesignatorCode": "FSG*SFR",
"fare": "121.86",
"taxes": [
{
"authority": {
"addressCountry": "US"
},
"name": "Transportation Tax",
"rate": 7.50,
"amount": "9.14"
}
],
"lineItems": [
{
"sequenceNumber": 1,
"description": "United States - September 11th Security Fee",
"additionalDescription": "Passenger Civil Aviation Security Service Fee",
"semanticsCode": "OTHER",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "2.24"
},
{
"sequenceNumber": 2,
"description": "United States - Passenger Facility Charge",
"additionalDescription": "",
"semanticsCode": "SEGFEE_AS_FEE",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "3.60"
},
{
"sequenceNumber": 3,
"description": "United States - Flight Segment Tax",
"additionalDescription": "",
"semanticsCode": "SEGFEE_AS_TAX",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "4.00"
}
]
},
{
"originationAirportIATACode": "GFK",
"originationDateTime": "2015-12-30T17:19:00-0500",
"destinationAirportIATACode": "MSP",
"destinationDateTime": "2015-12-30T18:34:00-0500",
"flightNumber": "OO 4656",
"couponNumber": "D187322",
"operatingAirlineCode": "DL",
"marketingCarrier": "DL1768Z",
"operatingCarrier": "OO4656B",
"classOfServiceCode": "T",
"fareBasisCode": "YAD1234",
"ticketDesignatorCode": "FSG*SFR",
"fare": "140.14",
"taxes": [
{
"authority": {
"addressCountry": "US"
},
"name": "Transportation Tax",
"rate": 7.50,
"amount": "10.51"
}
],
"lineItems": [
{
"sequenceNumber": 1,
"description": "United States - September 11th Security Fee",
"additionalDescription": "Passenger Civil Aviation Security Service Fee",
"semanticsCode": "OTHER",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "2.58"
},
{
"sequenceNumber": 2,
"description": "United States - Passenger Facility Charge",
"additionalDescription": "",
"semanticsCode": "SEGFEE_AS_FEE",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "4.14"
},
{
"sequenceNumber": 3,
"description": "United States - Flight Segment Tax",
"additionalDescription": "",
"semanticsCode": "SEGFEE_AS_TAX",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "4.00"
}
]
},
{
"originationAirportIATACode": "MSP",
"originationDateTime": "2015-12-30T19:25:00-0500",
"destinationAirportIATACode": "SEA",
"destinationDateTime": "2015-12-30T21:15:00-0700",
"flightNumber": "DL 2536",
"couponNumber": "D187322",
"operatingAirlineCode": "DL",
"marketingCarrier": "DL2536Z",
"operatingCarrier": "DL2536B",
"classOfServiceCode": "T",
"fareBasisCode": "YAD1234",
"ticketDesignatorCode": "FSG*SFR",
"fare": "194.98",
"taxes": [
{
"authority": {
"addressCountry": "US"
},
"name": "Transportation Tax",
"rate": 7.50,
"amount": "14.62"
}
],
"lineItems": [
{
"sequenceNumber": 1,
"description": "United States - September 11th Security Fee",
"additionalDescription": "Passenger Civil Aviation Security Service Fee",
"semanticsCode": "OTHER",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "3.58"
},
{
"sequenceNumber": 2,
"description": "United States - Passenger Facility Charge",
"additionalDescription": "",
"semanticsCode": "SEGFEE_AS_FEE",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "5.76"
},
{
"sequenceNumber": 3,
"description": "United States - Flight Segment Tax",
"additionalDescription": "",
"semanticsCode": "SEGFEE_AS_TAX",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "4.00"
}
]
}
]
},
{
"number": "0062698215637",
"recordLocator": "CU9GEF",
"issueDateTime": "2015-11-29T19:15:55-0700",
"pseudoCityCode": "SEA",
"IATAAgencyNumber": "87654321",
"agencyName": "ACME Airlines",
"passengerName": "John Smith",
"fare": "609.31",
"coupons": [
{
"originationAirportIATACode": "SEA",
"originationDateTime": "2015-12-25T09:00:00-0700",
"destinationAirportIATACode": "MSP",
"destinationDateTime": "2015-12-25T14:14:00-0500",
"flightNumber": "DL 1768",
"couponNumber": "D167693",
"operatingAirlineCode": "DL",
"marketingCarrier": "DL1768",
"operatingCarrier": "DL1768",
"classOfServiceCode": "T",
"fareBasisCode": "YHRT15",
"ticketDesignatorCode": "FSG*SFR",
"fare": "152.33",
"taxes": [
{
"authority": {
"addressCountry": "US"
},
"name": "Transportation Tax",
"rate": 7.50,
"amount": "11.42"
}
],
"lineItems": [
{
"sequenceNumber": 1,
"description": "United States - September 11th Security Fee",
"additionalDescription": "Passenger Civil Aviation Security Service Fee",
"semanticsCode": "OTHER",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "2.80"
},
{
"sequenceNumber": 2,
"description": "United States - Passenger Facility Charge",
"additionalDescription": "",
"semanticsCode": "SEGFEE_AS_FEE",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "4.50"
},
{
"sequenceNumber": 3,
"description": "United States - Flight Segment Tax",
"additionalDescription": "",
"semanticsCode": "SEGFEE_AS_TAX",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "4.00"
}
]
},
{
"originationAirportIATACode": "MSP",
"originationDateTime": "2015-12-25T15:25:00-0500",
"destinationAirportIATACode": "GFK",
"destinationDateTime": "2015-12-25T16:50:00-0500",
"flightNumber": "OO 4656",
"couponNumber": "D187322",
"operatingAirlineCode": "DL",
"marketingCarrier": "DL1768Z",
"operatingCarrier": "OO4656B",
"classOfServiceCode": "T",
"fareBasisCode": "YAD1234",
"ticketDesignatorCode": "FSG*SFR",
"fare": "121.86",
"taxes": [
{
"authority": {
"addressCountry": "US"
},
"name": "Transportation Tax",
"rate": 7.50,
"amount": "9.14"
}
],
"lineItems": [
{
"sequenceNumber": 1,
"description": "United States - September 11th Security Fee",
"additionalDescription": "Passenger Civil Aviation Security Service Fee",
"semanticsCode": "OTHER",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "2.24"
},
{
"sequenceNumber": 2,
"description": "United States - Passenger Facility Charge",
"additionalDescription": "",
"semanticsCode": "SEGFEE_AS_FEE",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "3.60"
},
{
"sequenceNumber": 3,
"description": "United States - Flight Segment Tax",
"additionalDescription": "",
"semanticsCode": "SEGFEE_AS_TAX",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "4.00"
}
]
},
{
"originationAirportIATACode": "GFK",
"originationDateTime": "2015-12-30T17:19:00-0500",
"destinationAirportIATACode": "MSP",
"destinationDateTime": "2015-12-30T18:34:00-0500",
"flightNumber": "OO 4656",
"couponNumber": "D187322",
"operatingAirlineCode": "DL",
"marketingCarrier": "DL1768Z",
"operatingCarrier": "OO4656B",
"classOfServiceCode": "T",
"fareBasisCode": "YAD1234",
"ticketDesignatorCode": "FSG*SFR",
"fare": "140.14",
"taxes": [
{
"authority": {
"addressCountry": "US"
},
"name": "Transportation Tax",
"rate": 7.50,
"amount": "10.51"
}
],
"lineItems": [
{
"sequenceNumber": 1,
"description": "United States - September 11th Security Fee",
"additionalDescription": "Passenger Civil Aviation Security Service Fee",
"semanticsCode": "OTHER",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "2.58"
},
{
"sequenceNumber": 2,
"description": "United States - Passenger Facility Charge",
"additionalDescription": "",
"semanticsCode": "SEGFEE_AS_FEE",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "4.14"
},
{
"sequenceNumber": 3,
"description": "United States - Flight Segment Tax",
"additionalDescription": "",
"semanticsCode": "SEGFEE_AS_TAX",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "4.00"
}
]
},
{
"originationAirportIATACode": "MSP",
"originationDateTime": "2015-12-30T19:25:00-0500",
"destinationAirportIATACode": "SEA",
"destinationDateTime": "2015-12-30T21:15:00-0700",
"flightNumber": "DL 2536",
"couponNumber": "D187322",
"operatingAirlineCode": "DL",
"marketingCarrier": "DL2536Z",
"operatingCarrier": "DL2536B",
"classOfServiceCode": "T",
"fareBasisCode": "YAD1234",
"ticketDesignatorCode": "FSG*SFR",
"fare": "194.98",
"taxes": [
{
"authority": {
"addressCountry": "US"
},
"name": "Transportation Tax",
"rate": 7.50,
"amount": "14.62"
}
],
"lineItems": [
{
"sequenceNumber": 1,
"description": "United States - September 11th Security Fee",
"additionalDescription": "Passenger Civil Aviation Security Service Fee",
"semanticsCode": "OTHER",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "3.58"
},
{
"sequenceNumber": 2,
"description": "United States - Passenger Facility Charge",
"additionalDescription": "",
"semanticsCode": "SEGFEE_AS_FEE",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "5.76"
},
{
"sequenceNumber": 3,
"description": "United States - Flight Segment Tax",
"additionalDescription": "",
"semanticsCode": "SEGFEE_AS_TAX",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "4.00"
}
]
}
]
}
],
"lineItems": [
{
"sequenceNumber": 1,
"description": "United States - September 11th Security Fee",
"additionalDescription": "Passenger Civil Aviation Security Service Fee",
"semanticsCode": "OTHER",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "22.40"
},
{
"sequenceNumber": 2,
"description": "United States - Passenger Facility Charge",
"additionalDescription": "",
"semanticsCode": "SEGFEE_AS_FEE",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "36.00"
}
]
}
Generated Receipt Image

Car Rental
Receipt Data
{
"taxInvoice": true,
"reference": "ABCD1234",
"dateTime": "2016-09-29T15:05:00-0800",
"total": "112.71",
"taxesTotal": "8.27",
"subtotal": "104.44",
"currencyCode": "USD",
"seller": {
"name": "ACME Corporation",
"description": "",
"taxId": "123-21213",
"location": {
"name": "SNA Airport",
"number": "SNA34393",
"latitude": 47.616667,
"longitude": -122.333333,
"internetAddress": "https://www.acmecorporation.com",
"emailAddress": "sna_airport@acmecorporation.com",
"telephoneNumber": "123-456-7890",
"faxNumber": "",
"address": {
"streetAddress": "1 Airport Way",
"addressLocality": "Seattle",
"addressRegion": "WA",
"addressCountry": "US",
"postalCode": "90001"
}
}
},
"taxes": [
{
"authority": {
"addressCountry": "US",
"addressRegion": "WA"
},
"name": "Local Sales Tax",
"rate": 8.80,
"amount": "8.27"
}
],
"payments": [
{
"amount": "112.71",
"cardDetail": {
"cardType": "American Express",
"creditCardId": "1009",
"authorizationCode": "AB987654321"
}
}
],
"startDateTime": "2014-11-05T15:05:00-0800",
"endDateTime": "2014-11-07T15:05:00-0800",
"rentalDays": 2,
"discounts": [{
"discountCode": "NO-IRS",
"discountName": "The Family of the King shall pay less",
"discountRate": "Per Mile"
}
],
"rentalAgreementNumber": "570344843",
"confirmationNumber": "",
"vehicle": {
"registrationNumber": "",
"description": "KIA SORENTO 2WD",
"classReservedCode": "IDAR",
"classRentedCode": "IDAR",
"classChargedCode": "IDAR",
"engineSize": "2000",
"fuelType": "Petrol"
},
"distance": {
"totalDistance": 345.6,
"unit": "mi"
},
"odometerReadingOut": 31548,
"odometerReadingIn": 31893,
"additionalDriver": false,
"pickupLocation": {
"name": "House of Stark",
"address": {
"streetAddress": "1 Wolf Road",
"addressLocality": "Winterfell",
"addressCountry": "GB"
}
},
"dropoffLocation": {
"name": "The Iron Throne",
"address": {
"streetAddress": "42 Shadowblack Lane",
"addressLocality": "King's Landing",
"addressCountry": "GB"
}
},
"lineItems": [
{
"sequenceNumber": 1,
"reference": "",
"description": "2 DY@ 47.00",
"additionalDescription": "",
"semanticsCode": "DAYS",
"quantity": 1,
"total": "94.00",
"taxes": [
{
"authority": {
"addressCountry": "US",
"addressRegion": "CA"
},
"name": "Local Sales Tax",
"rate": 8.80,
"amount": "8.27"
}
]
},
{
"sequenceNumber": 2,
"reference": "",
"description": "11.11% FEE",
"additionalDescription": "",
"semanticsCode": "AIRPORTFEE",
"quantity": 1,
"total": "10.44"
}
]
}
Generated Receipt Image

Hotel
Receipt Data
{
"taxInvoice": true,
"reference": "6343430",
"dateTime": "2016-09-29T15:05:00-0800",
"total": "749.95",
"subtotal": "652.67",
"taxesTotal": "97.28",
"currencyCode": "CAD",
"seller": {
"name": "ACME Corporation",
"description": "",
"taxId": "123-21213",
"location": {
"name": "ACME Hotels",
"number": "ACME34393",
"latitude": 47.616667,
"longitude": -122.333333,
"internetAddress": "https://www.acmecorporation.com",
"emailAddress": "sna_hotel@acmecorporation.com",
"telephoneNumber": "123-456-7890",
"faxNumber": "",
"address": {
"streetAddress": "1 Hotel Way",
"addressLocality": "Seattle",
"addressRegion": "WA",
"addressCountry": "US",
"postalCode": "90001"
}
}
},
"taxes": [
{
"authority": {
"addressCountry": "CA"
},
"name": "Hotel Room Tax",
"rate": 11.00,
"amount": "66.88"
},
{
"authority": {
"addressCountry": "CA"
},
"name": "GST",
"rateType": "Standard",
"rate": 5.00,
"amount": "30.4"
}
],
"payments": [
{
"amount": "749.95",
"cardDetail": {
"cardType": "American Express",
"creditCardId": "1002",
"authorizationCode": "548283"
}
}
],
"property": {
"name": "Grand Hotel",
"number": "",
"latitude": 49.280011,
"longitude": -123.117024,
"internetAddress": "",
"emailAddress": "",
"telephoneNumber": "123-456-1999",
"faxNumber": "123-456-2502",
"address": {
"streetAddress": "433 Hotel Street",
"addressLocality": "Vancouver",
"addressRegion": "BC",
"addressCountry": "CA",
"postalCode": "v6b 6l9"
}
},
"checkInDateTime": "2016-08-25T21:11:00-0700",
"checkOutDateTime": "2016-08-27T11:09:00-0700",
"guests": [
{
"guestNameRecord": "ACME-Axxxxxxx1899",
"firstName": "Jon",
"lastName": "Snow",
"address": {
"streetAddress": "111 Black Castle",
"addressLocality": "Toronto",
"addressRegion": "ON",
"addressCountry": "CA",
"postalCode": "M2P 2B8"
}
}
],
"numberInParty": 1,
"room": {
"roomNumber": "1601",
"averageDailyRoomRate": "304.00"
},
"nightsStayed": 2,
"lineItems": [
{
"sequenceNumber": 1,
"dateTime": "2016-04-25T18:00:00-0700",
"reference": "RT1601",
"description": "Room Chrg Retail",
"semanticsCode": "ROOMRATE",
"quantity": 1,
"total": "304.00",
"taxes": [
{
"authority": {
"addressCountry": "CA"
},
"name": "Hotel Room Tax",
"rate": 11.00,
"amount": "33.44"
},
{
"authority": {
"addressCountry": "CA"
},
"name": "GST",
"rateType": "Standard",
"rate": 5.00,
"amount": "15.20"
}
]
},
{
"sequenceNumber": 2,
"dateTime": "2016-04-25T18:00:00-0700",
"reference": "RT1601",
"description": "Destination Marketing Fee",
"semanticsCode": "FEE",
"quantity": 1,
"total": "4.56"
},
{
"sequenceNumber": 3,
"dateTime": "2016-04-26T18:00:00-0700",
"reference": "4071",
"description": "Hidden Bar and Lounge",
"semanticsCode": "MINIBAR",
"quantity": 1,
"total": "31.55"
},
{
"sequenceNumber": 4,
"dateTime": "2016-04-26T18:00:00-0700",
"reference": "RT1601",
"description": "Room Chrg Retail",
"semanticsCode": "ROOMRATE",
"quantity": 1,
"total": "304.00",
"taxes": [
{
"authority": {
"addressCountry": "CA"
},
"name": "Hotel Room Tax",
"rate": 11.00,
"amount": "33.44"
},
{
"authority": {
"addressCountry": "CA"
},
"name": "GST",
"rateType": "Standard",
"rate": 5.00,
"amount": "15.20"
}
]
},
{
"sequenceNumber": 5,
"dateTime": "2016-04-26T18:00:00-0700",
"reference": "RT1601",
"description": "Destination Marketing Fee",
"semanticsCode": "FEE",
"quantity": 1,
"total": "4.56"
}
]
}
Generated Receipt Image

Ground Transport
Receipt Data
{
"taxInvoice": true,
"reference": "ADBXTF25",
"dateTime": "2016-09-29T15:39:46-0700",
"total": "65.00",
"taxesTotal": "5.69",
"subtotal": "59.87",
"currencyCode": "USD",
"broker": {
"name": "ACME Corporation",
"taxId": "123-21213",
"location": {
"name": "Seattle Downtown",
"number": "C3404",
"latitude": 47.6097,
"longitude": -122.3331,
"internetAddress": "http://www.acmecorporation.com/",
"emailAddress": "groundtransport@acmecorporation.com",
"telephoneNumber": "206-000-0000",
"faxNumber": "",
"address": {
"streetAddress": "1 Ground Transport Way",
"addressLocality": "Seattle",
"addressRegion": "WA",
"addressCountry": "US",
"postalCode": "90001"
}
}
},
"seller": {
"name": "John Smith",
"location": {
"address": {
"streetAddress": "225 42nd Ave S",
"addressLocality": "Seattle",
"addressRegion": "WA",
"addressCountry": "US",
"postalCode": "98103"
}
}
},
"taxes": [
{
"authority": {
"addressCountry": "US",
"addressRegion": "WA"
},
"name": "Local Sales Tax",
"rate": 9.50,
"amount": "5.69"
}
],
"payments": [
{
"amount": "65.00",
"cardDetail": {
"cardType": "Visa",
"creditCardId": "4321",
"authorizationCode": "AB123654789"
}
}
],
"classOfService": "BLACK",
"startDateTime": "2014-11-10T15:08:24-0500",
"endDateTime": "2014-11-10T15:39:46-0500",
"travelDuration": "PT21M22S",
"pickupLocation": {
"name": "Key Center Building, Bellevue, WA",
"latitude": 47.4436655,
"longitude": -122.2982266,
"address": {
"addressCountry": "US"
}
},
"dropoffLocation": {
"name": "Seattle-Tacoma International Airport, SeaTac, WA",
"latitude": 47.4489,
"longitude": -122.3094,
"address": {
"addressCountry": "US"
}
},
"distance": {
"totalDistance": 15.6,
"unit": "mi"
},
"driverNumber": "DFE154-8567",
"lineItems": [
{
"sequenceNumber": 1,
"reference": "",
"description": "Base Fare",
"additionalDescription": "",
"semanticsCode": "FEE",
"quantity": 1,
"total": "6.39",
"taxes": [
{
"authority": {
"addressCountry": "US",
"addressRegion": "WA"
},
"name": "Local Sales Tax",
"rate": 9.50,
"amount": "0.61"
}
]
},
{
"sequenceNumber": 2,
"reference": "",
"description": "Distance",
"additionalDescription": "",
"semanticsCode": "FEE",
"quantity": 1,
"total": "49.32",
"taxes": [
{
"authority": {
"addressCountry": "US",
"addressRegion": "WA"
},
"name": "Local Sales Tax",
"rate": 9.50,
"amount": "4.68"
}
]
},
{
"sequenceNumber": 3,
"reference": "",
"description": "Time",
"additionalDescription": "",
"semanticsCode": "FEE",
"quantity": 1,
"total": "4.16",
"taxes": [
{
"authority": {
"addressCountry": "US",
"addressRegion": "WA"
},
"name": "Local Sales Tax",
"rate": 9.50,
"amount": "0.40"
}
]
},
{
"sequenceNumber": 4,
"reference": "",
"description": "Rounding Down",
"additionalDescription": "",
"semanticsCode": "DISCOUNT",
"quantity": 1,
"total": "-0.56"
}
]
}
Generated Receipt Image

Rail (Multiple Tickets)
Receipt Data
{
"taxInvoice": true,
"reference": "VDFG4567",
"dateTime": "2099-11-10T16:04:49-0700",
"total": "394.00",
"subtotal": "394.00",
"taxesTotal": "0.00",
"currencyCode": "GBP",
"itineraryLocator": "DSFJKLT4967",
"seller": {
"name": "ACME Corporation",
"description": "",
"taxId": "321-654321",
"location": {
"name": "Headquarters",
"number": "",
"latitude": 41.8819,
"longitude": -87.6278,
"internetAddress": "http://www.voyages-sncf.com",
"emailAddress": "info@uk.voyages-sncf.com",
"telephoneNumber": "0330 822 0333",
"address": {
"streetAddress": "34 Tower View",
"addressLocality": "Kings Hill, WEST MALLING",
"addressCountry": "GB",
"postalCode": "ME19 4ED"
}
}
},
"payments": [
{
"amount": "394.00",
"cardDetail": {
"cardType": "American Express",
"creditCardId": "4002"
}
}
],
"railTickets": [
{
"ticketNumber": "C123456",
"recordLocator": "AZT222XFT9",
"issueDateTime": "2015-04-30T12:37:55-0700",
"passengerName": "John Doe",
"fare": "197.00",
"segments": [
{
"departureStation": "Paris Est",
"departureDateTime": "2015-11-25T10:00:00-0700",
"arrivalStation": "Frankfurt Main HBF",
"arrivalDateTime": "2015-11-26T12:00:00+0900",
"trainNumber": "9557",
"trainType": "TGV",
"classOfServiceCode": "First Class",
"fare": "98.50"
},
{
"departureStation": "Frankfurt Main HBF",
"departureDateTime": "2015-11-27T10:00:00-0700",
"arrivalStation": "Paris Est",
"arrivalDateTime": "2015-11-28T12:00:00+0900",
"trainNumber": "9558",
"trainType": "TGV",
"classOfServiceCode": "First Class",
"fare": "98.50"
}
]
},
{
"ticketNumber": "C123457",
"recordLocator": "AZT222XFT9",
"issueDateTime": "2015-04-30T12:37:55-0700",
"passengerName": "Jane Doe",
"fare": "197.00",
"segments": [
{
"departureStation": "Paris Est",
"departureDateTime": "2015-11-25T10:00:00-0700",
"arrivalStation": "Frankfurt Main HBF",
"arrivalDateTime": "2015-11-26T12:00:00+0900",
"trainNumber": "9557",
"trainType": "TGV",
"classOfServiceCode": "First Class",
"fare": "98.50"
},
{
"departureStation": "Frankfurt Main HBF",
"departureDateTime": "2015-11-27T10:00:00-0700",
"arrivalStation": "Paris Est",
"arrivalDateTime": "2015-11-28T12:00:00+0900",
"trainNumber": "9558",
"trainType": "TGV",
"classOfServiceCode": "First Class",
"fare": "98.50"
}
]
}
],
"lineItems": [
{
"sequenceNumber": 1,
"semanticsCode": "FEE",
"description": "Credit Card Fee",
"dateTime": "2015-11-10T16:04:49-0700",
"subtotal": "4.92",
"total": "4.92"
}
]
}
Generated Receipt Image

Response Codes
Success Codes
| Code | Message | Information |
|---|---|---|
| 200 | OK | Your GET request succeeded. |
| 201 | Created | Your POST request succeeded. Please note that even though your request passed validation, the service still needs to create your receipt. Because of this processing time, your receipt might not be available for retrieval immediately. |
| 202 | Accepted | Your request was accepted. Please note that even though your request was accepted, the service still needs to process your receipt. Because of this processing time, your receipt might not be available for retrieval immediately. |
Failure Codes
| Code | Message | Response Body | Information |
|---|---|---|---|
| 400 | Bad Request | validationErrors JSON object |
An error occurred while validating your post against the JSON schema. The validationErrors object will contain detailed information about what caused the validation to fail. |
| Request body could not be parsed | This means that the body of your request was empty, or there was an error parsing it. | ||
| Link header must be provided and include a URL to a known receipt schema | The link header cannot be null or empty, and must include one of the supported receipt type JSON schemas followed by ;rel=describedBy. A list of supported schemas can be retrieved from the /schemas endpoint of this service. |
||
| The specified receipt schema is not valid | The schema specified in the link header was valid, but an error occurred when the service attempted to fetch the schema internally. | ||
| 401 | Unauthorized | User ID in the URL must match the ID in the sub claim of the JWT | This response occurs when the JWT used for authentication is valid, but doesn't match the correct user. When using a user JWT, the request must be to a URL for the same user that is represented in the JWT. For more information on the process of obtaining a JWT, see the Authentication service documentation. |
| 403 | Forbidden | None | Authentication failed for some reason. A 403 will be returned if there is no JWT in the Authorization header of the request, or if the JWT is invalid or expired. This response is also for cases where the JWT does not include the scope required to fulfill the request. For more information on JWTs and scopes, see the Authentication service documentation. |
| 404 | Not Found | None | The receipt(s) you requested could not be found. Check that the receipt and/or user ID that you used are correct. |
| 413 | Max file size exceeded | None | The image you posted exceeded the limit of 5MB. |
| 415 | Unsupported Media Type | Specified Content-Type is not supported | The receipt service currently supports receipt data formatted as JSON. The Content-Type header must have the value application/json or the request will fail. |
| Invalid image type | Images must be .png, .jpg, .jpeg, .tiff, or .gif. |
||
| 500 | Internal Server Error | Internal error | This response is for generic internal server errors. Something went wrong, and we're probably already trying to fix it! |
| Unable to save receipt into the database | An error occurred while trying to update the state of the receipt. | ||
| Could not get available receipts | An error occurred while trying to fetch receipts for a user by state. |
REQUEST
Request v3
This API has been deprecated.
Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.
Learn more in the API Lifecycle & Deprecation Policy.
Concur Request automates the spend request and approval process for both travel and everyday expenses, giving you the data you need to accurately track and better control spending. By increasing visibility into planned expenses and up-to-date budget data, you can make strategic spending decisions before any spending actually occurs. The Request resource provides many abilities, including viewing requests and transition of requests into the workflow.
Versions
Retrieve all requests
GET /api/v3.0/travelrequest/requests
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
offset |
string |
query |
Starting page offset |
limit |
Int32 |
query |
Number of records to return (default 100) |
user |
string |
query |
The login ID of the user who owns this Request. The user must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter. |
status |
string |
query |
The Status search term specifies which travel request or approval status to return. If no Status value is sent, the default Status of Active will be used. |
modifiedAfter |
DateTime |
query |
This returns travel requests in which the associated dependents (header, entries, segments, allocations, attendees, comments) were modified after the specified date and time. This search term can be used along with other search terms to narrow the results. The date and time (if desired) should be in UTC. The format is: YYYY-MM-DDThh:mm:ss. |
modifiedBefore |
DateTime |
query |
This returns travel requests in which the associated dependents (header, entries, segments, allocations, attendees, comments) were modified before the specified date and time. This search term can be used along with other search terms to narrow the results. The date and time (if desired) should be in UTC. The format is: YYYY-MM-DDThh:mm:ss. |
withSegmentTypes |
Boolean |
query |
Pass true to populate the SegmentType field in the result. |
Retrieve a request by ID
GET /api/v3.0/travelrequest/requests/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required The Request ID |
user |
string |
query |
The login ID of the user. Optional. The user must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter. |
Submit a request by ID
POST /api/v3.0/travelrequest/requests/{id}/submit
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
The Request ID |
Schema
Request
| Name | Type | Format | Description |
|---|---|---|---|
AgencyOfficeName |
string |
- | The travel agency office name. |
AllocationFormID |
string |
- | The unique identifier of the Segment Form resource (See the "Forms" resource for more information). |
ApprovalLimitDate |
DateTime |
- | The date by which the Request must be approved. This element appears only when integrated with Concur Travel. |
ApprovalStatusCode |
string |
- | The code for the approval status the Request. |
ApprovalStatusName |
string |
- | The approval status of the Request. |
AuthorizedDate |
DateTime |
- | The date the Request was authorized. Format: YYYY-MM-DDThh:mm:ss. |
CashAdvances |
Array |
Cash Advance | This parent element has a CashAdvance child element for each cash advance. See the CashAdvance model for the full list of child elements. |
Comments |
Array |
Comment | This parent element has a Comment child element for each comment. See the Comment model for the full list of child elements. |
CreationDate |
DateTime |
- | The date of the Request was created. |
CurrencyCode |
string |
- | The 3-letter ISO 4217 currency code for the Request currency. The Request currency is defined as the Request creator's default reimbursement currency. |
CurrencyName |
string |
- | The currency name for the Request currency. The Request currency is defined as the Request creator's default reimbursement currency. |
Custom1 through Custom20 |
CustomField |
- | The details from the Custom fields. These fields may not have data, depending on the configuration. |
EmployeeName |
string |
- | The first, middle (or middle initial), and last name of the employee who created the Request. |
EndDate |
string |
- | The end date of the Request. |
EndTime |
string |
- | The end time for the Request. |
Entries |
Array |
Entry | This parent element has a RequestEntry child element for each entry. See the RequestEntry model for the full list of child elements. |
EverSentBack |
string |
- | Indicates whether the Request has ever been sent back to the employee. Format: Y/N |
Exceptions |
Array |
Exception | This parent element has an Exception child element for each exception. See the Exception model for the full list of child elements. |
ExtensionOf |
string |
- | The ID of the initial Request that this Request is an extension of or adendum to. |
HasException |
string |
- | Indicates whether the Request has exceptions. Format: Y/N |
HeaderFormID |
string |
- | The unique identifier of the Header Form resource (See the "Forms" resource for more information). |
LastModifiedDate |
DateTime |
- | The date the Request was last modified. Format: YYYY-MM-DDThh:mm:ss |
LoginID |
string |
- | The Concur login ID of the Request owner. |
Name |
string |
- | The name of the Request. |
PolicyID |
string |
- | The unique identifier of the policy that applies to this Request. Maximum length 64 characters. |
PolicyName |
string |
- | The name of the policy that applies to this Request. |
Purpose |
string |
- | The purpose of the Request. |
RequestID |
string |
- | The unique key for the Request. |
StartDate |
string |
- | The start date of the Request. |
StartTime |
string |
- | The start time for the Request. |
SubmitDate |
DateTime |
- | The date the Request was submitted. Format: YYYY-MM-DDThh:mm:ss. |
TotalApprovedAmount |
string |
- | The total amount of approved expenses in the Request. |
TotalPostedAmount |
string |
- | The total amount of the Request. |
TotalRemainingAmount |
string |
- | The total amount of expenses remaining in the Request. |
UserPermissions |
UserPermissions |
- | The actions that the user is allowed to perform on the Request. |
Cash Advance
| Name | Type | Format | Description |
|---|---|---|---|
AmountRequested |
string |
- | The amount requested in the cash advance, in the currency specified in the CurrencyCode element. |
ApprovalStatusName |
string |
- | The approval status of the cash advance. |
Comments |
Array |
Comment | This parent element has a Comment child element for each comment. Refer to the Comments model for the full list of child elements. |
CurrencyCode |
string |
- | The 3-letter ISO 4217 currency code for the cash advance currency. |
CurrencyName |
string |
- | The name of the currency for the cash advance. |
EmployeeCurrencyCode |
string |
- | The 3-letter ISO 4217 currency code for the employee's currency, also known as the home currency. |
EmployeeCurrencyName |
string |
- | The name of the employee's currency, also known as the home currency. |
ExchangeRate |
string |
- | The exchange rate that applies to the cash advance. |
IssueDate |
DateTime |
- | The issue date for the cash advance. |
RequestDate |
DateTime |
- | The date of cash advance request, obtained from the detailed cash advance record. |
StartingBalance |
string |
- | The initial balance for the cash advance. |
Comment
| Name | Type | Format | Description |
|---|---|---|---|
AuthorFirstName |
string |
- | The first name of the person who made the comment. |
AuthorLastName |
string |
- | The last name of the person who made the comment. |
CommentDateTime |
DateTime |
- | The time, in GMT, when the user made the comment. |
IsLatest |
bool |
- | Indicates that the comment is the last one. |
Value |
string |
- | The text of the Request header comment. |
Custom
| Name | Type | Format | Description |
|---|---|---|---|
Code |
string |
- | For list fields, this is the list item code. |
ListItemID |
string |
- | For list fields, this is the list item ID. |
Type |
string |
- | The custom field type. Possible values: Amount, Boolean, ConnectedList, Date, Integer, List, Number, Text |
Value |
string |
- | The value in the Org Unit or Custom field. For list fields, this is the name of the list item. Maximum length: 48 characters |
Entry
| Name | Type | Format | Description |
|---|---|---|---|
Allocations |
Array |
Allocation | This parent element has an Allocation child element for each associated allocation. See the Allocation model for the full list of child elements. |
ApprovedAmount |
string |
- | The approved amount of the Request entry in the Request currency. |
Comments |
Array |
Comment | This parent element has a Comment child element for each comment. See the Comments model for the full list of child elements. |
Custom1 through Custom40 |
CustomField |
- | The details from the Custom fields. These fields may not have data, depending on the configuration. |
EntryDescription |
string |
- | The description of the Request entry. |
EntryFormID |
string |
- | The unique identifier of the Entry Form resource (See the "Forms" resource for more information). |
Exceptions |
Array |
Exception | This parent element has an Exception child element for each exception. See the Exception model for the full list of child elements. |
ExchangeRate |
string |
- | The exchange rate that applies to the entry. |
ExpenseTypeName |
string |
- | The expense type name. |
ForeignAmount |
string |
- | The foreign amount of the Request entry. |
ForeignCurrencyCode |
string |
- | The 3-letter ISO 4217 currency code for the foreign currency amount of the Request entry. |
ForeignCurrencyName |
string |
- | The name of the currency for the foreign amount. |
LastModifiedDate |
DateTime |
- | The date the entry was last modified. Format: YYYY-MM-DDThh:mm:ss |
OrgUnit1 through OrgUnit6 |
CustomField |
- | The details from the Org Unit custom fields. These fields may not have data, depending on the configuration. |
PostedAmount |
string |
- | The posted amount of the Request entry in the Request currency. |
RemainingAmount |
string |
- | The remaining amount of the Request entry in the Request currency. |
Segments |
Array |
Segment | This parent element has a Segment child element for each segment associated with the travel request. See the Segment model for the full list of child elements. |
TransactionDate |
DateTime |
- | The date of the Request entry. |
TripType |
string |
- | ['ONE_WAY' or 'ROUND_TRIP' or 'MULTI_STOP'] Trip type of the air or rail segment. Possible values are: ONE_WAY, ROUND_TRIP and MULTI_STOP. |
Allocation
| Name | Type | Format | Description |
|---|---|---|---|
Custom1 through Custom20 |
CustomField |
- | The details from the Custom fields. These fields may not have data, depending on the configuration. |
Percentage |
string |
- | The percentage of the expense that is included in this allocation. |
Exception
| Name | Type | Format | Description |
|---|---|---|---|
Code |
string |
- | The system exception code defined for the exception. Example: BADCODE |
Level |
int |
- | The numeric level associated with the exception. Example: 99 |
Message |
string |
- | The user-facing message defined for the exception. |
Segment
| Name | Type | Format | Description |
|---|---|---|---|
ApprovedAmount |
string |
- | The approved amount of the segment in the Request currency. |
ArrivalDate |
string |
- | The arrival date of the segment. |
ArrivalTime |
string |
- | The arrival time of the segment. |
ClassOfServiceCode |
string |
- | The Class of Service Code from Concur Travel. Appears only when the Request is integrated with Concur Travel. |
Comments |
Array |
Comment | The list of comments added for this segment. |
Custom1 through Custom40 |
CustomField |
- | The details from the Custom fields. These fields may not have data, depending on the configuration. |
DepartureDate |
string |
- | The departure date of the segment. |
DepartureTime |
string |
- | The departure time of the segment. |
Exceptions |
Array |
Exception | This parent element has an Exception child element for each exception. Refer to the Exception model for the full list of child elements. |
ExchangeRate |
string |
- | The exchange rate that applies to the segment. |
FlightNumber |
string |
- | The flight number for air segments. Appears only when Request is integrated with Concur Travel. |
ForeignAmount |
string |
- | The foreign currency amount of the segment. |
ForeignCurrencyCode |
string |
- | The 3-letter ISO 4217 currency code for the foreign currency amount of the segment. |
ForeignCurrencyName |
string |
- | The name of the currency for the foreign amount of the segment. |
FormTypeCode |
string |
- | The code for form type of the segment type. |
FromLocationDetail |
string |
- | The code for the starting location. |
FromLocationID |
string |
- | The unique identifier of the departure location. (See the "Locations" resource for more information). |
FromLocationName |
string |
- | The name of the starting location. |
IsAgencyBooked |
string |
- | Indicates whether the air segment was agency booked. Format: Y/N. |
IsSelfBooked |
string |
- | Indicates whether the air segment was self booked. Format: Y/N. |
LastModifiedDate |
DateTime |
- | The date the segment was last modified. Format: YYYY-MM-DDThh:mm:ss |
OutboundSegmentID |
string |
- | REQ_SEGMENT_OUTBOUND_ID |
PostedAmount |
string |
- | The posted amount of the segment in the Request currency. |
RecordLocator |
string |
- | Appears only when the Request is integrated with Concur Travel. |
RemainingAmount |
string |
- | The remaining amount of the segment in the Request currency. |
SegmentFormID |
string |
- | The unique identifier of the Segment Form resource (See the "Forms" resource for more information). |
SegmentLocator |
string |
- | The unique identifier for the Concur Travel segment associated with this segment. Appears only when the Request is integrated with Concur Travel. |
SegmentType |
string |
- | The type of itinerary segment. Format: air, car, hotel, rail, dining, event, ground, taxi, parking, other and so on |
SegmentTypeCode |
string |
- | The code for the type of itinerary segment. |
ToLocationDetail |
string |
- | The code for the ending location. |
ToLocationID |
string |
- | The unique identifier of the arrival location. (See the "Locations" resource for more information). |
ToLocationName |
string |
- | The name of the ending location. |
TripLocator |
string |
- | The unique identifier for the Concur Travel trip associated with this segment. Appears only when the Request is integrated with Concur Travel. |
User Permissions
| Name | Type | Format | Description |
|---|---|---|---|
Links |
Array |
Link | The actions that the user is allowed to perform on the Request. |
Link
| Name | Type | Format | Description |
|---|---|---|---|
Action |
string |
- | The action that the user is allowed to perform on the resource. |
Method |
string |
- | The method of the request. Possible values: GET, POST, PUT and DELETE. |
Url |
string |
- | The URL of the resource that the user can access. |
Travel Request v4 - Request Proposals Resources
Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.
Send proposals within a Request
Scopes
travelrequest.write - Refer to Scope Usage for full details.
HTTP Request
URI Template
POST {datacenter}/travelrequest/v4/requests/{requestUuid}/agencyproposals
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
requestUuid |
string |
- | Required The unique identifier of the Request. |
userId |
string |
- | The unique identifier of the travel agent assigned to the travel agency linked to the proposal feature. Required when connecting with a Company token, if empty a 400 missingRequiredParam error code will be displayed. |
Payload
HTTP Response
HTTP Status Codes
To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.
Payload
Example
HTTP Request
POST https://us.api.concursolutions.com/travelrequest/v4/requests/{requestUuid}/agencyproposals
Accept: application/json
Authorization: Bearer {token}
HTTP Response
200 OK
{
"agencyProposalEntries": [
{
"agencyProposalSegments": [
{
"booked": true,
"confirmationNumber": "RecordLocator246",
"endDate": "2021-05-02",
"endTime": "21:18",
"pnr": "OYY5T",
"policyCompliantLevel": 50,
"proposalSegmentType": "AIR",
"startDate": "2021-05-02",
"startTime": "20:06",
"vendorName": "AIR FRANCE",
"timeZone": "UTC+12:00",
"classOfService": "Economy",
"duration": 60,
"flightNumber": "AF030",
"endLocation": {
"iataCode": "CDG"
},
"startLocation": {
"iataCode": "OSL"
}
},
{
"booked" : true,
"confirmationNumber": "RecordLocator246",
"endDate": "2021-05-01",
"endTime": "08:30",
"pnr": "OYY5T",
"policyCompliantLevel": 50,
"proposalSegmentType": "AIR",
"startDate": "2021-05-01",
"startTime": "07:24",
"vendorName": "AIR FRANCE",
"timeZone": "UTC+12:00",
"classOfService": "Economy",
"duration": 60,
"flightNumber": "AF029",
"startLocation": {
"iataCode": "CDG"
},
"endLocation": {
"iataCode": "OSL"
}
}
],
"transactionAmount": {
"currency": "EUR",
"value": 300.16
},
"transactionDate": "2021-03-29T03:04:05.678Z"
},
{
"agencyProposalSegments": [
{
"booked": true,
"comments": "Staying at Liberty Hotel",
"confirmationNumber": "RecordLocator123",
"endDate": "2021-05-02",
"endTime": "10:00",
"pnr": "OCC5T",
"policyCompliantLevel": 50,
"proposalSegmentType": "HOTEL",
"startDate": "2021-05-01",
"startTime": "18:00",
"vendorName": "ACCOR",
"timeZone": "UTC+12:00",
"location": {
"countryCode": "NO",
"city": "Oslo"
},
"name": "Liberty Hotel",
"roomDescription": "Single",
"providerPhone": "+3260000000",
"locationDetail": "No smoker",
"address": "Fjord Place"
}
],
"transactionAmount": {
"currency": "EUR",
"value": 146.00
},
"transactionDate": "2021-03-29T03:04:05.678Z"
}
],
"agencyProposalType": "API",
"approvalLimitDate": "2021-04-24T03:04:05.678Z",
"autoSelect": false,
"booked": true,
"comments": "",
"itineraryLocator": "AR15U",
"policyCompliant": true,
"proposalOrder": 1,
"proposalBatchSize": 2,
"providerMessageId": "XKRDFGE",
"status": "PROPOSAL",
"totalPostedAmount": {
"currency": "EUR",
"value": 446.16
}
}
{
"agencyProposalEntries": [
{
"agencyProposalSegments": [
{
"booked": true,
"confirmationNumber": "RecordLocator246",
"endDate": "2021-05-02",
"endTime": "20:18",
"pnr": "OYY5T",
"policyCompliantLevel": 50,
"proposalSegmentType": "AIR",
"startDate": "2021-05-02",
"startTime": "19:06",
"vendorName": "AIR FRANCE",
"timeZone": "UTC+12:00",
"classOfService": "Economy",
"duration": 60,
"flightNumber": "AF031",
"endLocation": {
"iataCode": "CDG"
},
"startLocation": {
"iataCode": "OSL"
}
},
{
"booked" : true,
"confirmationNumber": "RecordLocator246",
"endDate": "2021-05-01",
"endTime": "09:30",
"pnr": "OYY5T",
"policyCompliantLevel": 50,
"proposalSegmentType": "AIR",
"startDate": "2021-05-01",
"startTime": "08:24",
"vendorName": "AIR FRANCE",
"timeZone": "UTC+12:00",
"classOfService": "Economy",
"duration": 60,
"flightNumber": "AF030",
"startLocation": {
"iataCode": "CDG"
},
"endLocation": {
"iataCode": "OSL"
}
}
],
"transactionAmount": {
"currency": "EUR",
"value": 350.17
},
"transactionDate": "2021-03-29T03:04:05.678Z"
},
{
"agencyProposalSegments": [
{
"booked": false,
"comments": "Staying at Opera Hotel",
"confirmationNumber": "RecordLocator123",
"endDate": "2021-05-02",
"endTime": "10:00",
"pnr": "OCC5T",
"policyCompliantLevel": 50,
"proposalSegmentType": "HOTEL",
"startDate": "2021-05-01",
"startTime": "18:00",
"vendorName": "ACCOR",
"timeZone": "UTC+12:00",
"location": {
"countryCode": "NO",
"city": "Oslo"
},
"name": "Opera Hotel",
"roomDescription": "Double",
"providerPhone": "+3260000000",
"locationDetail": "No smoker",
"address": "Ulriken Place"
}
],
"transactionAmount": {
"currency": "EUR",
"value": 200.00
},
"transactionDate": "2021-03-29T03:04:05.678Z"
}
],
"agencyProposalType": "API",
"approvalLimitDate": "2021-04-26T03:04:05.678Z",
"autoSelect": false,
"booked": true,
"comments": "",
"itineraryLocator": "AR15U",
"policyCompliant": true,
"proposalOrder": 2,
"proposalBatchSize": 2,
"providerMessageId": "XKRDFGE",
"status": "PROPOSAL",
"totalPostedAmount": {
"currency": "EUR",
"value": 550.17
}
}
Get the list of agency proposals
Scopes
travelrequest.write - Refer to Scope Usage for full details.
HTTP Request
URI Template
GET {datacenter}/travelrequest/v4/requests/{requestUuid}/agencyproposals
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
requestUuid |
string |
- | Required The unique identifier of the Request. |
Payload
None.
HTTP Response
HTTP Status Codes
To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.
Payload
Example
HTTP Request
GET https://us.api.concursolutions.com/travelrequest/v4/requests/{requestUuid}/agencyproposals
Accept: application/json
Authorization: Bearer {token}
HTTP Response
200 OK
[
{
"proposalUuid": "c76eb8f5-10fa-4840-95e0-3c730b0cad46",
"agencyProposalEntries": [
{
"proposalEntryUuid": "38607d43-477b-4544-9cc3-3bcc224db838",
"matchingExpense": {},
"transactionDate": "2021-03-29T03:04:06.000Z",
"comments": "Staying at Opera Hotel",
"transactionAmount": {
"value": 200.00000000,
"currency": "EUR"
},
"agencyProposalSegments": [
{
"address": "Ulriken Place",
"booked": false,
"comments": "Staying at Opera Hotel",
"confirmationNumber": "RecordLocator123",
"endDate": "2021-05-02",
"endTime": "10:00",
"location": {
"countryCode": "NO",
"city": "Oslo"
},
"locationDetail": "No smoker",
"matchingSegmentLeg": {},
"name": "Opera Hotel",
"pnr": "OCC5T",
"policyCompliant": false,
"policyCompliantLevel": 50,
"proposalSegmentType": "HOTEL",
"proposalSegmentUuid": "ea706941-462b-4d63-a28f-9ac560adcb5e",
"providerPhone": "+3260000000",
"roomDescription": "Double",
"segmentTypeCode": "HOTEL",
"startDate": "2021-05-01",
"startTime": "18:00",
"timeZone": "UTC+12:00",
"vendorName": "ACCOR"
}
]
},
{
"proposalEntryUuid": "654fb089-0fed-4891-ac2f-da2f480dfab4",
"matchingExpense": {},
"transactionDate": "2021-03-29T03:04:06.000Z",
"comments": "",
"transactionAmount": {
"value": 350.17000000,
"currency": "EUR"
},
"agencyProposalSegments": [
{
"booked": true,
"classOfService": "Economy",
"confirmationNumber": "RecordLocator246",
"duration": 60,
"endDate": "2021-05-02",
"endLocation": {
"iataCode": "CDG"
},
"endTime": "20:18",
"flightNumber": "AF031",
"matchingSegmentLeg": {},
"pnr": "OYY5T",
"policyCompliant": false,
"policyCompliantLevel": 50,
"proposalSegmentType": "AIR",
"proposalSegmentUuid": "e43b521a-b1b1-48a5-b368-74d36d3fc56e",
"segmentTypeCode": "AIRFR",
"startDate": "2021-05-02",
"startLocation": {
"iataCode": "OSL"
},
"startTime": "19:06",
"timeZone": "UTC+12:00",
"vendorName": "AIR FRANCE"
},
{
"booked": true,
"classOfService": "Economy",
"confirmationNumber": "RecordLocator246",
"duration": 60,
"endDate": "2021-05-01",
"endLocation": {
"iataCode": "OSL"
},
"endTime": "09:30",
"flightNumber": "AF030",
"matchingSegmentLeg": {},
"pnr": "OYY5T",
"policyCompliant": false,
"policyCompliantLevel": 50,
"proposalSegmentType": "AIR",
"proposalSegmentUuid": "f9c55ba6-bdcf-4e65-b189-40f343076784",
"segmentTypeCode": "AIRFR",
"startDate": "2021-05-01",
"startLocation": {
"iataCode": "CDG"
},
"startTime": "08:24",
"timeZone": "UTC+12:00",
"vendorName": "AIR FRANCE"
}
]
}
],
"agencyProposalType": "API",
"approvalLimitDate": "2021-04-26T03:04:06.000Z",
"autoSelect": false,
"booked": true,
"comments": "",
"importDate": "2021-03-29T09:44:36.000Z",
"itineraryLocator": "AR15U",
"policyCompliant": true,
"proposal": true,
"proposalBatchSize": 2,
"proposalOrder": 2,
"providerMessageId": "XKRDFGE",
"selected": false,
"status": "PROPOSAL",
"totalPostedAmount": {
"value": 550.17000000,
"currency": "EUR"
}
},
{
"proposalUuid": "d6de71be-3716-48cb-b133-a82e03e25bfe",
"agencyProposalEntries": [
{
"proposalEntryUuid": "99a44f02-b1c3-4712-af72-77cabc6f725d",
"matchingExpense": {
"id": "1ECBCB87CE27FE4AB9B5D76E20E05B98"
},
"transactionDate": "2021-03-29T03:04:06.000Z",
"comments": "",
"transactionAmount": {
"value": 300.16000000,
"currency": "EUR"
},
"agencyProposalSegments": [
{
"booked": true,
"classOfService": "Economy",
"confirmationNumber": "RecordLocator246",
"duration": 60,
"endDate": "2021-05-02",
"endLocation": {
"iataCode": "CDG"
},
"endTime": "21:18",
"flightNumber": "AF030",
"matchingSegmentLeg": {
"id": "25C97F6CD6AD9F4AB5E80D6F61730D2D"
},
"pnr": "OYY5T",
"policyCompliant": false,
"policyCompliantLevel": 50,
"proposalSegmentType": "AIR",
"proposalSegmentUuid": "7835f703-2f6b-4b71-96ef-0445355f24f8",
"segmentTypeCode": "AIRFR",
"startDate": "2021-05-02",
"startLocation": {
"iataCode": "OSL"
},
"startTime": "20:06",
"timeZone": "UTC+12:00",
"vendorName": "AIR FRANCE"
},
{
"booked": true,
"classOfService": "Economy",
"confirmationNumber": "RecordLocator246",
"duration": 60,
"endDate": "2021-05-01",
"endLocation": {
"iataCode": "OSL"
},
"endTime": "08:30",
"flightNumber": "AF029",
"matchingSegmentLeg": {
"id": "51B98284E6232A40A600E9E92710CADF"
},
"pnr": "OYY5T",
"policyCompliant": false,
"policyCompliantLevel": 50,
"proposalSegmentType": "AIR",
"proposalSegmentUuid": "9e363bdc-0ef4-4332-b5ad-98ab5b759d8f",
"segmentTypeCode": "AIRFR",
"startDate": "2021-05-01",
"startLocation": {
"iataCode": "CDG"
},
"startTime": "07:24",
"timeZone": "UTC+12:00",
"vendorName": "AIR FRANCE"
}
]
},
{
"proposalEntryUuid": "b4b50e4d-4082-43ee-8a08-ccc6996fcfd3",
"matchingExpense": {
"id": "CA964E3216D64746A4CFF3EFD49410C6"
},
"transactionDate": "2021-03-29T03:04:06.000Z",
"comments": "Staying at Liberty Hotel",
"transactionAmount": {
"value": 146.00000000,
"currency": "EUR"
},
"agencyProposalSegments": [
{
"address": "Fjord Place",
"booked": true,
"comments": "Staying at Liberty Hotel",
"confirmationNumber": "RecordLocator123",
"endDate": "2021-05-02",
"endTime": "10:00",
"location": {
"countryCode": "NO",
"city": "Oslo"
},
"locationDetail": "No smoker",
"matchingSegmentLeg": {
"id": "8D364364F706994994BA226B3356D9FE"
},
"name": "Liberty Hotel",
"pnr": "OCC5T",
"policyCompliant": false,
"policyCompliantLevel": 50,
"proposalSegmentType": "HOTEL",
"proposalSegmentUuid": "72ad0da9-ebe6-459b-94e0-4db1cafe173b",
"providerPhone": "+3260000000",
"roomDescription": "Single",
"segmentTypeCode": "HOTEL",
"startDate": "2021-05-01",
"startTime": "18:00",
"timeZone": "UTC+12:00",
"vendorName": "ACCOR"
}
]
}
],
"agencyProposalType": "API",
"approvalLimitDate": "2021-04-24T03:04:06.000Z",
"autoSelect": false,
"booked": true,
"comments": "",
"importDate": "2021-03-29T09:44:34.000Z",
"itineraryLocator": "AR15U",
"policyCompliant": true,
"proposal": true,
"proposalBatchSize": 2,
"proposalOrder": 1,
"providerMessageId": "XKRDFGE",
"selected": true,
"status": "PROPOSAL",
"totalPostedAmount": {
"value": 446.16000000,
"currency": "EUR"
}
}
]
Agency proposals
| Name | Type | Format | Description |
|---|---|---|---|
agencyProposalType |
string |
- | Required The agency proposal type value. Supported value: API. |
importDate |
timestamp |
YYYY-MM-DDThh:mm:ss.SSS'Z |
Read only The date of the import. |
proposalUuid |
string |
- | Read only The unique identifier of one proposal for a Request. |
providerMessageId |
string |
- | The unique identifier of the client’s batch of proposal. |
proposalBatchSize |
integer |
- | Required Size of the client’s batch of proposal. Note: If this value is greater than 1, the Request will not be sent back to the traveler as long as the expected number of proposals (respective proposalOrder) are not integrated into the Request. |
proposalOrder |
integer |
- | Required Sequence order of the proposal for the request. |
booked |
boolean |
- | Required If true, this trip is (or has to be) handled by a travel agency. |
approvalLimitDate |
- | yyyy-MM-dd'T'HH:mm:ss.SSS'Z' |
Limit approval date of the proposal. Past this date, the proposal will not be viable any more. |
status |
string |
- | Required Supported values: PROPOSAL,CONFIRMED,TICKETISSUED. |
proposal |
boolean |
- | Read only If true, this proposal is still in the PROPOSAL status. If false, the proposal status is CONFIRMED (tickets issued). |
comments |
string |
- | Free text. |
itineraryLocator |
string |
- | The unique identifier for Concur Travel itinerary. |
autoSelect |
boolean |
- | If true, the Request is approved and the confirmed proposal is sent back into the Request. Not managed yet. |
selected |
boolean |
- | Read only Value becomes true when that proposal is selected by the user. |
totalPostedAmount |
object |
Amount |
The total amount for that proposal. |
policyCompliant |
boolean |
- | If true, the the Agency Proposal is policy compliant. Default: true |
agencyProposalEntries |
array |
Agency proposal entry |
Minimum required: 1. |
Agency proposal entry
| Name | Type | Format | Description |
|---|---|---|---|
proposalEntryUuid |
string |
- | Read only The unique identifier of one entry in a proposal for a request. |
comments |
string |
- | Read only Concatenate the comments of underlying segments. |
transactionDate |
timestamp |
YYYY-MM-DDThh:mm:ss.SSS'Z |
Read only The date of the transaction in local time. |
transactionAmount |
object |
Amount |
The amount of this entry. |
exchangeRate |
object |
Exchange Rate |
Read only The exchange rate that applies to this entry. |
agencyProposalSegment |
array |
Agency proposal segment |
Minimum required: 1. |
Agency proposal segment
| Name | Type | Format | Description |
|---|---|---|---|
proposalSegmentUuid |
string |
- | Read only The unique identifier of one segment in a proposal for a request. |
pnr |
string |
- | Required The personal number of reservation. |
booked |
boolean |
- | Required If true, this trip is (or has to be) handled by a travel agency. |
policyCompliant |
boolean |
- | Read only If true, the Agency Proposal is policy compliant. true if policyComplianceLevel is 100. |
policyCompliantLevel |
integer |
- | A value between 0 & 100 that matches the segment compliance. 100 if fully policyCompliant, 0 if not compliant at all. Default value: 100. |
comments |
string |
- | Free text. |
startDate |
date |
yyyy-MM-dd |
The date of the beginning of this segment. |
startTime |
time |
yyyy-MM-dd |
The time of the beginning of this segment. Required if this field set as mandator for the corresponding segment. |
endDate |
date |
yyyy-MM-dd |
The date of the ending of this segment. |
endTime |
time |
yyyy-MM-dd |
The time of the ending of this segment. Required if this field set as mandator for the corresponding segment. |
vendorName |
string |
- | Required The vendor name for this segment. |
confirmationNumber |
string |
- | Required The record locator or confirmation number for the flight from the airline. |
proposalSegmentType |
string |
- | Required Supported values: AIR, RAIL, CAR, HOTEL, MISC |
segmentTypeCode |
object |
Segment Type |
Required The type of the segment. Supported values: AIRFR, CARRT, HOTEL, RAILF, MISC |
timeZone |
zoneId |
- | The time zone of the booking. Format: - Fixed offsets: a fully resolved offset from UTC/Greenwich, that uses the same offset for all local date-times; - Geographical regions: an area where a specific set of rules for finding the offset from UTC/Greenwich apply (default group is the IANA Time Zone Database (TZDB)). |
agencyProposalAirSegment |
array |
Agency proposal air segment |
Additional fields for Air segments. |
agencyProposalRailSegment |
array |
Agency proposal rail segment |
Additional fields for Rail segments. |
agencyProposalCarSegment |
array |
Agency proposal car segment |
Additional fields for Car segments. |
agencyProposalHotelSegment |
array |
Agency proposal hotel segment |
Additional fields for Hotel segments. |
agencyProposalMiscSegment |
array |
Agency proposal misc segment |
Additional fields for Misc segments. |
Agency proposal air segment
| Name | Type | Format | Description |
|---|---|---|---|
classOfService |
string |
- | Required The class of the air segment. |
duration |
integer |
- | Required The duration of the booked flight. Must be greater than 0. |
flightNumber |
string |
- | Required The flight number for the booking. |
seatNumber |
string |
- | The number of the seat. |
aircraft |
string |
- | The code of the aircraft type. |
mealPreference |
string |
- | The booked meal. |
departureTerminal |
string |
- | The departure terminal for the air segment leg. |
arrivalTerminal |
string |
- | The arrival terminal for the air segment leg. |
startLocation |
object |
Location |
Required The start location of the air segment leg (Air location schema). |
endLocation |
object |
Location |
Required The end location of the air segment leg (Air location schema). |
Agency proposal rail segment
| Name | Type | Format | Description |
|---|---|---|---|
classOfService |
string |
- | Required The class of the segment leg. |
duration |
integer |
- | Required The duration of the booked train. Must be greater than 0. |
trainNumber |
string |
- | Required The train number for the booking. |
wagonNumber |
string |
- | The number of the wagon. |
seatNumber |
string |
- | The number of the seat. |
startRailStation |
string |
- | The code for the starting station of the segment leg. |
startRailStationName |
string |
- | The name of the starting station of the segment leg. |
startLocation |
object |
Location |
Required The start location of the rail segment leg (Rail location schema). |
endRailStation |
string |
- | The code for the ending station of the segment leg. |
endRailStationName |
string |
- | The name of the ending station of the segment leg. |
endLocation |
object |
Location |
Required The end location of the rail segment leg (Rail location schema). |
mealPreference |
string |
- | The booked meal. |
Agency proposal car segment
| Name | Type | Format | Description |
|---|---|---|---|
airConditioning |
boolean |
- | Indicates if car has an air conditioner. Supported values: R - AC, N - No AC |
carEquipment |
string |
- | Any special equipment required by the renter. |
classOfService |
string |
- | The class of the segment leg. |
transmissionPreference |
string |
- | The character code that indicates if the car has auto-transmission. Supported values A - Auto, M - Manual |
dropOffCollectionPhoneNumber |
string |
- | The phone number for the drop-off address when the rental service offers drop-off. |
endLocation |
object |
Location |
Required The end location of the car segment leg (city location schema). |
pickupDeliveryPhoneNumber |
string |
- | The phone number for the pickup address when the rental service offers pickup. |
startLocation |
object |
Location |
Required The start location of the car segment leg (city location schema). |
startLocationDetail |
string |
- | Additional details about the start location. |
endLocationDetail |
string |
- | Additional details about the end location. |
Agency proposal hotel segment
| Name | Type | Format | Description |
|---|---|---|---|
name |
string |
- | Required The hotel name for the booking. |
roomDescription |
string |
- | The room description for the booking. Maximum Length: 2000 |
providerPhone |
string |
- | The phone number for the booking. |
location |
object |
Location |
Required The location of the hotel segment leg (city location schema). |
locationDetail |
string |
- | Additional details about the location. |
address |
string |
- | The address of the booking. |
postalCode |
string |
- | The address postal code of the booking. |
Agency proposal misc segment
| Name | Type | Format | Description |
|---|---|---|---|
name |
string |
- | Required The name for the booking. |
Travel Request v4 - Request Cash Advance Resources
Note: This cash advance detail endpoint is provided within the Concur Request API for feature parity purpose only. It is highly recommended to rely only on the list of cash advances link available in the Request payload response, and not on this cash advance detail URI presented below, which will be deprecated in the future.
Get the content of an existing cash advance
Scopes
travelrequest.write - Refer to Scope Usage for full details.
HTTP Request
URI Template
GET {datacenter}/travelrequest/v4/cashadvances/{cashAdvanceUuid}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
cashAdvanceUuid |
string |
- | Required The unique identifier of the cash advance. |
Payload
None.
HTTP Response
HTTP Status Codes
To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.
Payload
Example
HTTP Request
GET https://us.api.concursolutions.com/travelrequest/v4/cashadvances/{cashAdvanceUuid}
Accept: application/json
Authorization: Bearer {token}
HTTP Response
200 OK
[
{
"amountRequested": {
"value": 1.000000,
"currency": "USD",
"amount": 1.000000
},
"approvalStatus": {
"code": "C_PEND",
"name": "Pending Approval"
},
"cashAdvanceId: EF3E237ACAA3C449B808BA75BDD049FA,
"exchangeRate": {
"value": 1.00000000000000,
"operation": "MULTIPLY"
},
"requestDate": 2019-11-14:T10:39:00.000Z"
}
]
Travel Request v4 - Expected Expense Resources
Manage expected expenses attached to a Request.
- Create a new expected expense
- Get the list of expected expenses attached to a Request
- Get the content of an expected expense
- Update the content of an expected expense
- Delete an expected expense from the Request
- Get the list of comments for an existing expected expense
Create a new expected expense
Scopes
travelrequest.write - Refer to Scope Usage for full details.
HTTP Request
URI Template
POST {datacenter}/travelrequest/v4/requests/{requestUuid}/expenses
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
requestUuid |
string |
- | Required The unique identifier of the Request to which the expected expense is attached. |
userId |
string |
- | The unique identifier of the user performing the expected expense creation. Required when connecting with a Company token. If empty, a 400 missingRequiredParam error code will be displayed. |
Payload
HTTP Response
HTTP Status Codes
To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.
Payload
Expected Expense - The created expected expense.
Example
HTTP Request
POST https://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2/expenses
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}
{
"allocations": [
{
"allocationAmount": {
"currency": "USD",
"value": 122.38
},
"approvedAmount": {
"currency": "USD",
"value": 122.38
},
"percentEdited": false,
"percentage": 0,
"postedAmount": {
"currency": "USD",
"value": 122.38
},
"systemAllocation": false
}
],
"approvedAmount": {
"currency": "USD",
"value": 122.38
},
"businessPurpose": "additional punctual trip to South of France",
"exchangeRate": {
"operation": "MULTIPLY",
"value": 1
},
"expenseType": {
"id": "RAILF",
"name": "Train"
},
"lastComment": "",
"location": {
"id": "A168CDBA58AE42868961BC00278A91B3",
"countryCode": "FR",
"countrySubDivisionCode": "FR-75",
"city": "Paris",
"name": "Charles De Gaulle Intl"
},
"postedAmount": {
"currency": "USD",
"value": 122.38
},
"remainingAmount": {
"currency": "USD",
"value": 122.38
},
"transactionAmount": {
"currency": "USD",
"value": 122.38
},
"transactionDate": "2018-07-18T00:00:00Z",
"tripData": {
"agencyBooked": false,
"legs": [
{
"class": {
"code": "1ST",
"value": "05F71FA4ED235D479C6C7039F397DA79"
},
"endLocation": {
"countryCode": "FR",
"locationCode": "FRNCE",
"city": "Nice",
"name": "Cote D Azur"
},
"returnLeg": false,
"startDate": "2018-07-18",
"startLocation": {
"countryCode": "FR",
"locationCode": "FRCDG",
"city": "Paris",
"name": "ROISSY"
},
"startTime": "21:00",
"startLocationDetail": "none"
}
],
"segmentType": {
"category": "REQ_SEG_RAILF",
"code": "RAILF"
},
"selfBooked": false,
"tripType": "ONE_WAY"
}
}
HTTP Response
201 Created
{
"href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/0465224E14C23D4F8C2BC79A9D694BDD",
"id": "0465224E14C23D4F8C2BC79A9D694BDD",
"allocations": [
{
"allocationAmount": {
"value": 122.38,
"currency": "USD"
},
"approvedAmount": {
"value": 122.38,
"currency": "USD"
},
"allocationId": "28E1B1F50253CD47BE002DA7B2C218EE",
"postedAmount": {
"value": 122.38,
"currency": "USD"
},
"expenseId": "0465224E14C23D4F8C2BC79A9D694BDD",
"percentEdited": false,
"systemAllocation": true,
"percentage": 100
}
],
"approvedAmount": {
"value": 122.38,
"currency": "USD"
},
"exchangeRate": {
"value": 1,
"operation": "MULTIPLY"
},
"expenseType": {
"id": "TRAIN",
"name": "Train"
},
"postedAmount": {
"value": 122.38,
"currency": "USD"
},
"remainingAmount": {
"value": 122.38,
"currency": "USD"
},
"transactionAmount": {
"value": 122.38,
"currency": "USD"
},
"transactionDate": "2018-07-18T00:00:00.000Z",
"tripData": {
"agencyBooked": false,
"selfBooked": false,
"tripType": "ONE_WAY",
"legs": [
{
"class": {
"code": "1ST",
"value": "05F71FA4ED235D479C6C7039F397DA79"
},
"endLocation": {
"id": "CE4A6DCAC4A14D08803C28F6D5CB20F0",
"countryCode": "FR",
"countrySubDivisionCode": "FR-06",
"name": "Nice",
"locationCode": "IATA_NCE",
"locationType": "STD"
},
"id": "59508E1F979B4346AC6B38677ABE6404",
"returnLeg": false,
"startDate": "2018-07-18",
"startLocation": {
"id": "A168CDBA58AE42868961BC00278A91B3",
"countryCode": "FR",
"countrySubDivisionCode": "FR-75",
"name": "Paris",
"locationCode": "IATA_CDG",
"locationType": "STD"
},
"startLocationDetail": "none",
"startTime": "21:00"
}
],
"segmentType": {
"category": "REQ_SEG_RAILF",
"code": "RAILF"
}
}
}
Get the list of expected expenses attached to a Request
Scopes
travelrequest.write - Refer to Scope Usage for full details.
HTTP Request
URI Template
GET {datacenter}/travelrequest/v4/requests/{requestUuid}/expenses
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
requestUuid |
string |
- | Required The unique identifier of the Request. |
userId |
string |
- | The unique identifier of the user viewing the expected expenses attached to a Request. If empty when using a Company token the default system user will be assumed to perform the action. |
Payload
None.
HTTP Response
HTTP Status Codes
To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.
Payload
Expected Expense - List of expected expenses attached to a Request.
operations - [RFC 5988] Pagination links to next/prev/first/last page.
Example
HTTP Request
GET https://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2/expenses
Accept: application/json
Authorization: Bearer {token}
HTTP Response
200 OK
[
{
"href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/B5FB8991E390474E875D6FD5BB1FDAF1",
"id": "B5FB8991E390474E875D6FD5BB1FDAF1",
"allocations": [
{
"allocationAmount": {
"value": 324.56,
"currency": "USD"
},
"approvedAmount": {
"value": 324.56,
"currency": "USD"
},
"allocationId": "79249903DC18464AAAD61062EA383BD4",
"postedAmount": {
"value": 324.56,
"currency": "USD"
},
"expenseId": "B5FB8991E390474E875D6FD5BB1FDAF1",
"percentEdited": false,
"systemAllocation": true,
"percentage": 100
}
],
"approvedAmount": {
"value": 324.56,
"currency": "USD"
},
"exchangeRate": {
"value": 1,
"operation": "MULTIPLY"
},
"expenseType": {
"id": "AIRFR",
"name": "Airfare"
},
"postedAmount": {
"value": 324.56,
"currency": "USD"
},
"remainingAmount": {
"value": 324.56,
"currency": "USD"
},
"transactionAmount": {
"value": 324.56,
"currency": "USD"
},
"transactionDate": "2018-07-15T00:00:00.000Z",
"tripData": {
"agencyBooked": true,
"selfBooked": false,
"tripType": "ROUND_TRIP",
"legs": [
{
"class": {
"code": "1ST",
"value": "05F71FA4ED235D479C6C7039F397DA79"
},
"endLocation": {
"id": "4A33695120254EEC9261B24993DD413B",
"countryCode": "DE",
"countrySubDivisionCode": "DE-BE",
"city": "Berlin",
"iataCode": "BER",
"name": "Berlin(Alls)"
},
"id": "B0F356643B38BC419AFE60E050BB79A4",
"returnLeg": false,
"startDate": "2018-07-15",
"startLocation": {
"id": "A168CDBA58AE42868961BC00278A91B3",
"countryCode": "FR",
"countrySubDivisionCode": "FR-75",
"city": "Paris",
"iataCode": "CDG",
"name": "Charles De Gaulle Intl"
},
"startTime": "08:00"
},
{
"endLocation": {
"id": "A168CDBA58AE42868961BC00278A91B3",
"countryCode": "FR",
"countrySubDivisionCode": "FR-75",
"city": "Paris",
"iataCode": "CDG",
"name": "Charles De Gaulle Intl"
},
"id": "345475D42A53D948A6D60181759683E8",
"returnLeg": true,
"startDate": "2018-07-17",
"startLocation": {
"id": "4A33695120254EEC9261B24993DD413B",
"countryCode": "DE",
"countrySubDivisionCode": "DE-BE",
"city": "Berlin",
"iataCode": "BER",
"name": "Berlin(Alls)"
},
"startTime": "17:00"
}
],
"segmentType": {
"category": "REQ_SEG_AIRFR",
"code": "AIRFR"
}
}
},
{
"href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/D65BDBD5D980F6498D67A92B06A457B0",
"id": "D65BDBD5D980F6498D67A92B06A457B0",
"allocations": [
{
"allocationAmount": {
"value": 90,
"currency": "USD"
},
"approvedAmount": {
"value": 90,
"currency": "USD"
},
"allocationId": "FCAA998834A24949B01AC3C1D56AF4E3",
"postedAmount": {
"value": 90,
"currency": "USD"
},
"expenseId": "D65BDBD5D980F6498D67A92B06A457B0",
"percentEdited": false,
"systemAllocation": true,
"percentage": 100
}
],
"approvedAmount": {
"value": 90,
"currency": "USD"
},
"businessPurpose": "Airport to Office after arrival and before departure",
"exchangeRate": {
"value": 1,
"operation": "MULTIPLY"
},
"expenseType": {
"id": "TAXIX",
"name": "Taxi"
},
"location": {
"id": "34AB34319377456B95F5C2815CC72766",
"countryCode": "DE",
"countrySubDivisionCode": "DE-BER",
"city": "Berlin, GERMANY",
"name": "Berlin, GERMANY"
},
"postedAmount": {
"value": 90,
"currency": "USD"
},
"remainingAmount": {
"value": 90,
"currency": "USD"
},
"transactionAmount": {
"value": 90,
"currency": "USD"
},
"transactionDate": "2018-07-17T00:00:00.000Z"
},
{
"href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/C286A46A2DDF984EA28E41CEA278667D",
"id": "C286A46A2DDF984EA28E41CEA278667D",
"allocations": [
{
"allocationAmount": {
"value": 80,
"currency": "USD"
},
"approvedAmount": {
"value": 80,
"currency": "USD"
},
"allocationId": "780B3FA5B83EC24F922EBE7B5D4AED63",
"postedAmount": {
"value": 80,
"currency": "USD"
},
"expenseId": "C286A46A2DDF984EA28E41CEA278667D",
"percentEdited": false,
"systemAllocation": true,
"percentage": 100
}
],
"approvedAmount": {
"value": 80,
"currency": "USD"
},
"businessPurpose": "Estimated costs for 2 dinners in Berlin",
"exchangeRate": {
"value": 1,
"operation": "MULTIPLY"
},
"expenseType": {
"id": "DINNR",
"name": "Dinner"
},
"location": {
"id": "34AB34319377456B95F5C2815CC72766",
"countryCode": "DE",
"countrySubDivisionCode": "DE-BER",
"city": "Berlin, GERMANY",
"name": "Berlin, GERMANY"
},
"postedAmount": {
"value": 80,
"currency": "USD"
},
"remainingAmount": {
"value": 80,
"currency": "USD"
},
"transactionAmount": {
"value": 80,
"currency": "USD"
},
"transactionDate": "2018-07-17T00:00:00.000Z"
}
]
Get the content of an expected expense
Scopes
travelrequest.write - Refer to Scope Usage for full details.
HTTP Request
URI Template
GET {datacenter}/travelrequest/v4/expenses/{expenseUuid}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
expenseUuid |
string |
- | Required The unique identifier of the expected expense. |
userId |
string |
- | The unique identifier of the user viewing the expected expense. If empty when using a Company token the default system user will be assumed to perform the action. |
Payload
None.
HTTP Response
HTTP Status Codes
To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.
Payload
Expected Expense - The expected expense having {expenseUuid} as unique identifier.
Example 1 - for a Request segment
HTTP Request
GET https://us.api.concursolutions.com/travelrequest/v4/expenses/B5FB8991E390474E875D6FD5BB1FDAF1
Accept: application/json
Authorization: Bearer {token}
HTTP Response
200 OK
{
"href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/B5FB8991E390474E875D6FD5BB1FDAF1",
"id": "B5FB8991E390474E875D6FD5BB1FDAF1",
"allocations": [
{
"allocationAmount": {
"value": 324.56,
"currency": "USD"
},
"approvedAmount": {
"value": 324.56,
"currency": "USD"
},
"allocationId": "79249903DC18464AAAD61062EA383BD4",
"postedAmount": {
"value": 324.56,
"currency": "USD"
},
"expenseId": "B5FB8991E390474E875D6FD5BB1FDAF1",
"percentEdited": false,
"systemAllocation": true,
"percentage": 100
}
],
"approvedAmount": {
"value": 324.56,
"currency": "USD"
},
"comments": {
"href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/2F9FB5CE3AC2C74C9AC3D4AB3A83C0DA/comments",
"id": "2F9FB5CE3AC2C74C9AC3D4AB3A83C0DA",
"template": "http://us.api.concursolutions.com/travelrequest/v4/expenses/{id}/comments"
},
"exchangeRate": {
"value": 1,
"operation": "MULTIPLY"
},
"expenseType": {
"id": "AIRFR",
"name": "Airfare"
},
"parentRequest": {
"href": "https://us.api.concursolutions.com/travelrequest/v4/request/224AF3CDCC2A5244A37C72FA5770C6F2",
"id": "224AF3CDCC2A5244A37C72FA5770C6F2",
"template": "http://us.api.concursolutions.com/travelrequest/v4/request/{requestUuid}"
},
"postedAmount": {
"value": 324.56,
"currency": "USD"
},
"remainingAmount": {
"value": 324.56,
"currency": "USD"
},
"transactionAmount": {
"value": 324.56,
"currency": "USD"
},
"transactionDate": "2018-07-15T00:00:00.000Z",
"tripData": {
"agencyBooked": true,
"selfBooked": false,
"tripType": "ROUND_TRIP",
"legs": [
{
"class": {
"code": "1ST",
"value": "05F71FA4ED235D479C6C7039F397DA79"
},
"endLocation": {
"id": "4A33695120254EEC9261B24993DD413B",
"countryCode": "DE",
"countrySubDivisionCode": "DE-BE",
"city": "Berlin",
"iataCode": "BER",
"name": "Berlin(Alls)"
},
"id": "B0F356643B38BC419AFE60E050BB79A4",
"returnLeg": false,
"startDate": "2018-07-15",
"startLocation": {
"id": "A168CDBA58AE42868961BC00278A91B3",
"countryCode": "FR",
"countrySubDivisionCode": "FR-75",
"city": "Paris",
"iataCode": "CDG",
"name": "Charles De Gaulle Intl"
},
"startTime": "08:00"
},
{
"endLocation": {
"id": "A168CDBA58AE42868961BC00278A91B3",
"countryCode": "FR",
"countrySubDivisionCode": "FR-75",
"city": "Paris",
"iataCode": "CDG",
"name": "Charles De Gaulle Intl"
},
"id": "345475D42A53D948A6D60181759683E8",
"returnLeg": true,
"startDate": "2018-07-17",
"startLocation": {
"id": "4A33695120254EEC9261B24993DD413B",
"countryCode": "DE",
"countrySubDivisionCode": "DE-BE",
"city": "Berlin",
"iataCode": "BER",
"name": "Berlin(Alls)"
},
"startTime": "17:00"
}
],
"segmentType": {
"category": "REQ_SEG_AIRFR",
"code": "AIRFR"
}
}
}
Example 2 - for a Request expected expense
HTTP Request
GET https://us.api.concursolutions.com/travelrequest/v4/expenses/C286A46A2DDF984EA28E41CEA278667D
Accept: application/json
Authorization: Bearer {token}
HTTP Response
200 OK
{
"href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/C286A46A2DDF984EA28E41CEA278667D",
"id": "C286A46A2DDF984EA28E41CEA278667D",
"allocations": [
{
"allocationAmount": {
"value": 80,
"currency": "USD"
},
"approvedAmount": {
"value": 80,
"currency": "USD"
},
"allocationId": "780B3FA5B83EC24F922EBE7B5D4AED63",
"postedAmount": {
"value": 80,
"currency": "USD"
},
"expenseId": "C286A46A2DDF984EA28E41CEA278667D",
"percentEdited": false,
"systemAllocation": true,
"percentage": 100
}
],
"approvedAmount": {
"value": 80,
"currency": "USD"
},
"businessPurpose": "Estimated costs for 2 dinners in Berlin",
"exchangeRate": {
"value": 1,
"operation": "MULTIPLY"
},
"expenseType": {
"id": "DINNR",
"name": "Dinner"
},
"location": {
"id": "34AB34319377456B95F5C2815CC72766",
"countryCode": "DE",
"countrySubDivisionCode": "DE-BER",
"city": "Berlin, GERMANY",
"name": "Berlin, GERMANY"
},
"parentRequest": {
"href": "https://us.api.concursolutions.com/travelrequest/v4/request/224AF3CDCC2A5244A37C72FA5770C6F2",
"id": "224AF3CDCC2A5244A37C72FA5770C6F2",
"template": "http://us.api.concursolutions.com/travelrequest/v4/request/{requestUuid}"
},
"postedAmount": {
"value": 80,
"currency": "USD"
},
"remainingAmount": {
"value": 80,
"currency": "USD"
},
"transactionAmount": {
"value": 80,
"currency": "USD"
},
"transactionDate": "2018-07-17T00:00:00.000Z"
}
Update the content of an expected expense
Scopes
travelrequest.write - Refer to Scope Usage for full details.
HTTP Request
URI Template
PUT {datacenter}/travelrequest/v4/expenses/{expenseUuid}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
expenseUuid |
string |
- | Required The unique identifier of the expected expense to update. |
userId |
string |
- | The unique identifier of the user performing the expected expense update. Required when connecting with a Company token. If empty, a 400 missingRequiredParam error code will be displayed. |
Payload
HTTP Response
HTTP Status Codes
To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.
Payload
Expected Expense - The expected expense having {expenseUuid} as unique identifier after update.
Example
HTTP Request
PUT https://us.api.concursolutions.com/travelrequest/v4/expenses/B5FB8991E390474E875D6FD5BB1FDAF1
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}
{
"id": "B5FB8991E390474E875D6FD5BB1FDAF1",
"allocations": [
{
"allocationAmount": {
"value": 432.45,
"currency": "USD"
},
"approvedAmount": {
"value": 432.45,
"currency": "USD"
},
"allocationId": "79249903DC18464AAAD61062EA383BD4",
"postedAmount": {
"value": 432.45,
"currency": "USD"
},
"expenseId": "B5FB8991E390474E875D6FD5BB1FDAF1",
"percentEdited": false,
"systemAllocation": true,
"percentage": 100
}
],
"approvedAmount": {
"value": 432.45,
"currency": "USD"
},
"exchangeRate": {
"value": 1,
"operation": "MULTIPLY"
},
"expenseType": {
"id": "AIRFR",
"name": "Airfare"
},
"postedAmount": {
"value": 432.45,
"currency": "USD"
},
"remainingAmount": {
"value": 432.45,
"currency": "USD"
},
"transactionAmount": {
"value": 432.45,
"currency": "USD"
},
"transactionDate": "2018-07-16T00:00:00.000Z",
"tripData": {
"agencyBooked": true,
"selfBooked": false,
"tripType": "ROUND_TRIP",
"legs": [
{
"class": {
"code": "1ST",
"value": "05F71FA4ED235D479C6C7039F397DA79"
},
"endLocation": {
"countryCode": "DE",
"city": "Berlin",
"iataCode": "BER",
"name": "Berlin(Alls)"
},
"id": "B0F356643B38BC419AFE60E050BB79A4",
"returnLeg": false,
"startDate": "2018-07-16",
"startLocation": {
"countryCode": "FR",
"city": "Paris",
"iataCode": "CDG",
"name": "Charles De Gaulle Intl"
},
"startTime": "07:00"
},
{
"endLocation": {
"countryCode": "FR",
"city": "Paris",
"iataCode": "CDG",
"name": "Charles De Gaulle Intl"
},
"id": "345475D42A53D948A6D60181759683E8",
"returnLeg": true,
"startDate": "2018-07-18",
"startLocation": {
"countryCode": "DE",
"city": "Berlin",
"iataCode": "BER",
"name": "Berlin(Alls)"
},
"startTime": "18:00"
}
],
"segmentType": {
"category": "REQ_SEG_AIRFR",
"code": "AIRFR"
}
}
}
HTTP Response
200 OK
{
"href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/B5FB8991E390474E875D6FD5BB1FDAF1",
"id": "B5FB8991E390474E875D6FD5BB1FDAF1",
"allocations": [
{
"allocationAmount": {
"value": 432.45,
"currency": "USD"
},
"approvedAmount": {
"value": 432.45,
"currency": "USD"
},
"allocationId": "79249903DC18464AAAD61062EA383BD4",
"postedAmount": {
"value": 432.45,
"currency": "USD"
},
"expenseId": "B5FB8991E390474E875D6FD5BB1FDAF1",
"percentEdited": false,
"systemAllocation": true,
"percentage": 100
}
],
"approvedAmount": {
"value": 432.45,
"currency": "USD"
},
"exchangeRate": {
"value": 1,
"operation": "MULTIPLY"
},
"expenseType": {
"id": "AIRFR",
"name": "Airfare"
},
"parentRequest": {
"href": "https://us.api.concursolutions.com/travelrequest/v4/request/224AF3CDCC2A5244A37C72FA5770C6F2",
"id": "224AF3CDCC2A5244A37C72FA5770C6F2",
"template": "http://us.api.concursolutions.com/travelrequest/v4/request/{requestUuid}"
},
"postedAmount": {
"value": 432.45,
"currency": "USD"
},
"remainingAmount": {
"value": 432.45,
"currency": "USD"
},
"transactionAmount": {
"value": 432.45,
"currency": "USD"
},
"transactionDate": "2018-07-16T00:00:00.000Z",
"tripData": {
"agencyBooked": true,
"selfBooked": false,
"tripType": "ROUND_TRIP",
"legs": [
{
"class": {
"code": "1ST",
"value": "05F71FA4ED235D479C6C7039F397DA79"
},
"endLocation": {
"id": "4A33695120254EEC9261B24993DD413B",
"countryCode": "DE",
"countrySubDivisionCode": "DE-BE",
"city": "Berlin",
"iataCode": "BER",
"name": "Berlin(Alls)"
},
"id": "B0F356643B38BC419AFE60E050BB79A4",
"returnLeg": false,
"startDate": "2018-07-16",
"startLocation": {
"id": "A168CDBA58AE42868961BC00278A91B3",
"countryCode": "FR",
"countrySubDivisionCode": "FR-75",
"city": "Paris",
"iataCode": "CDG",
"name": "Charles De Gaulle Intl"
},
"startTime": "07:00"
},
{
"endLocation": {
"id": "A168CDBA58AE42868961BC00278A91B3",
"countryCode": "FR",
"countrySubDivisionCode": "FR-75",
"city": "Paris",
"iataCode": "CDG",
"name": "Charles De Gaulle Intl"
},
"id": "345475D42A53D948A6D60181759683E8",
"returnLeg": true,
"startDate": "2018-07-18",
"startLocation": {
"id": "4A33695120254EEC9261B24993DD413B",
"countryCode": "DE",
"countrySubDivisionCode": "DE-BE",
"city": "Berlin",
"iataCode": "BER",
"name": "Berlin(Alls)"
},
"startTime": "18:00"
}
],
"segmentType": {
"category": "REQ_SEG_AIRFR",
"code": "AIRFR"
}
}
}
Delete an expected expense from the Request
Scopes
travelrequest.write - Refer to Scope Usage for full details.
HTTP Request
URI Template
DELETE {datacenter}/travelrequest/v4/expenses/{expenseUuid}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
expenseUuid |
string |
- | Required The unique identifier of the expected expense to delete. |
userId |
string |
- | The unique identifier of the user performing the deletion of the expected expense. Required when connecting with a Company token. If empty, a 400 missingRequiredParam error code will be displayed. |
Payload
None.
HTTP Response
HTTP Status Codes
To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.
Payload
None.
Example
HTTP Request
DELETE https://us.api.concursolutions.com/travelrequest/v4/expenses/D65BDBD5D980F6498D67A92B06A457B0
Accept: application/json
Authorization: Bearer {token}
HTTP Response
200 OK
true
Get the list of comments for an existing expected expense
Scopes
travelrequest.write - Refer to Scope Usage for full details.
HTTP Request
URI Template
GET {datacenter}/travelrequest/v4/expenses/{expenseUuid}/comments
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
expenseUuid |
string |
- | Required The unique identifier of the expected expense. |
userId |
string |
- | The unique identifier of the user getting the content of the comments. Required when connecting with a Company token. If empty, a 400 missingRequiredParam error code will be displayed. |
Payload
None.
HTTP Response
HTTP Status Codes
To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.
Payload
Example
HTTP Request
GET https://us.api.concursolutions.com/travelrequest/v4/expenses/B5FB8991E390474E875D6FD5BB1FDAF1/comments
Accept: application/json
Authorization: Bearer {token}
HTTP Response
200 OK
[
{
"author": {
"firstName": "Steve",
"lastName": "Smith"
},
"creationDateTime": "2019-07-12T11:51:14.000Z",
"isLatest": true,
"value": "I have reviewed the required amount, too expensive. You are allowed to a maximum of 100 USD for a business meal"
},
{
"author": {
"firstName": "John",
"lastName": "Doe"
},
"creationDateTime": "2019-07-12T11:11:39.000Z",
"isLatest": false,
"value": "Please review the required amount for approval"
}
]
Travel Request v4 - Request Policy Resources
Get the list of existing Request policies for a given user
Scopes
travelrequest.write - Refer to Scope Usage for full details.
HTTP Request
URI Template
GET {datacenter}/travelrequest/v4/userpolicies
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
userId |
string |
- | The unique identifier of the user for whom the list of Request policies will be retrieved. Required when connecting with a Company token. If empty, a 400 missingRequiredParam error. |
Payload
None.
HTTP Response
HTTP Status Codes
To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.
Payload
Example
HTTP Request
GET https://us.api.concursolutions.com/travelrequest/v4/userpolicies
Accept: application/json
Authorization: Bearer {token}
HTTP Response
200 OK
[
{
"href": "https://us.api.concursolutions.com/travelrequest/v4/userpolicies/F4C8BD31CA9D4D6292795BE687EB9B2A",
"id": "F4C8BD31CA9D4D6292795BE687EB9B2A",
"name": "Internal training Request policy"
},
{
"href": "https://us.api.concursolutions.com/travelrequest/v4/userpolicies/F10E6059B5A14A4C80327FE387491026",
"id": "F10E6059B5A14A4C80327FE387491026",
"name": "Client meeting Request policy"
}
]
Travel Request v4 - Request Resources
- Create a new Request
- Get the list of existing Requests
- Get the content of an existing Request
- Update the content of an existing Request
- Delete an existing Request
- Get the list of comments for an existing Request
- Get the list of cash advances assigned to an existing Request
- Get the list of exceptions linked to an existing Request
Create a new Request
Scopes
travelrequest.write - Refer to Scope Usage for full details.
HTTP Request
URI Template
POST {datacenter}/travelrequest/v4/requests
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
userId |
string |
- | The unique identifier of the Request owner for whom the Request will be created. The corresponding user name will be displayed in the audit trail of the Request. Required when connecting with a Company token, if empty a 400 missingRequiredParam error code will be displayed. |
Payload
Since this endpoint is performing a Request creation, specifying an id field in the payload is not allowed.
A newly allocated id value will be returned upon successful Request creation.
HTTP Response
HTTP Status Codes
To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.
Payload
Request - The created Request.
Example
HTTP Request
POST https://us.api.concursolutions.com/travelrequest/v4/requests
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}
{
"businessPurpose": "Trip to Lyon for company training",
"comment": "Company training requires to go to Lyon",
"custom1": {
"value": "Training part of IT Service"
},
"custom2": {
"value": "8422A66A9B0142458020D9BCD4351D38"
},
"custom3": {
"value": "5A0F9AF6B92E34468698040C915688BF"
},
"custom4": {
"value": "3F54AE68BA66EF49A5984E5197202A4D"
},
"endDate": "2018-07-03",
"endTime": "22:00",
"startDate": "2018-07-01",
"startTime": "07:15",
"name": "Company Training - JULY 2018",
"mainDestination": {
"city": "Lyon, FRANCE",
"countryCode": "FR",
"countrySubDivisionCode": "FR-69",
"name": "Lyon, FRANCE"
},
"policy": {
"id": "F4C8BD31CA9D4D6292795BE687EB9B2A"
},
"travelAgency": {
"id": "2EC038D7C3CBBE4ABA0914425064D34F"
}
}
HTTP Response
201 Created
{
"href": "https://us.api.concursolutions.com/travelrequest/v4/requests/CED5E9CD8FC1424488F9331ACF956E73",
"id": "CED5E9CD8FC1424488F9331ACF956E73",
"approvalStatus": {
"code": "NOT_SUBMITTED",
"name": "Not Submitted"
},
"approved": false,
"businessPurpose": "Trip to Lyon for company training",
"canceledPostApproval": false,
"closed": false,
"comment": "Company training requires to go to Lyon",
"creationDate": "2018-05-25T08:08:59.000Z",
"custom1": {
"value": "Training part of IT Service"
},
"custom2": {
"code": "CEN3",
"value": "8422A66A9B0142458020D9BCD4351D38"
},
"custom3": {
"code": "CEN3PRO1",
"value": "5A0F9AF6B92E34468698040C915688BF"
},
"custom4": {
"code": "TRAINING",
"value": "3F54AE68BA66EF49A5984E5197202A4D"
},
"endDate": "2018-07-03",
"endTime": "22:00",
"everSentBack": false,
"expenses": [],
"highestExceptionLevel": "WARNING",
"lastModified": "2018-05-25T08:08:59.000Z",
"mainDestination": {
"countryCode": "FR",
"countrySubDivisionCode": "FR-69",
"city": "Lyon, FRANCE",
"name": "Lyon, FRANCE"
},
"name": "Company Training - JULY 2018",
"owner": {
"firstName": "John",
"id": "c0d9894b-98e2-48d5-86f9-1decde90dd15",
"lastName": "Doe"
},
"pendingApproval": false,
"policy": {
"id": "F4C8BD31CA9D4D6292795BE687EB9B2A"
},
"requestId": "333U",
"startDate": "2018-07-01",
"startTime": "07:15",
"totalApprovedAmount": {
"value": 0,
"currency": "USD"
},
"totalPostedAmount": {
"value": 0,
"currency": "USD"
},
"totalRemainingAmount": {
"value": 0,
"currency": "USD"
},
"travelAgency": {
"href": "https://us.api.concursolutions.com/travelrequest/v4/travelagencies/2EC038D7C3CBBE4ABA0914425064D34F",
"id": "2EC038D7C3CBBE4ABA0914425064D34F",
"template": "https://https://us.api.concursolutions.com/travelrequest/v4/travelagencies/{id}"
},
"type": {
"code": "TRAVEL",
"label": "Travel"
},
"operations": [
{
"rel": "submit",
"href": "https://us.api.concursolutions.com/travelrequest/v4/requests/CED5E9CD8FC1424488F9331ACF956E73/submit"
}
]
}
Get the list of existing Requests
Scopes
travelrequest.write - Refer to Scope Usage for full details.
HTTP Request
URI Template
GET {datacenter}/travelrequest/v4/requests
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
view |
string |
- | Name of the view defining the scope of the Requests to get. Supported values:ALL: Get all existing Requests for a user (relevant only for the traveler).ACTIVEGet all active Requests. Does not include cancelled Requests. Approved Requests included are aged less than three months based on current date and must not be in closed status.UNSUBMITTED: Get all the unsubmitted Requests (relevant only for the traveler).PENDING: Get all the Requests that are submitted but not yet approved (relevant only for the traveler).VALIDATED: Get all the approved Requests for a user (relevant only for the traveler). Closed Requests are included in this view.APPROVED: Get all the approved Requests by a user (relevant only for the approver). Closed Requests are included in this view.CANCELED: Get all the cancelled Requests for a user (relevant only for the traveler). Cancelled could include closed/not closed Requests.CLOSED: Get all the closed Requests for a user (relevant only for the traveler). Includes canceled then closed Request as well as approved then closed Requests.SUBMITTED: Get all the submitted Requests for a user (relevant only for the traveler). Submitted does not include cancelled requests.TOAPPROVE: Get all Requests to be approved by the user (relevant only for the approver).PENDINGEBOOKING: Approved Requests awaiting Concur Travel booking(s).PENDINGPROPOSAL: Get all Requests submitted to a Travel Agency (TMC) step (relevant only for the TMC agent), userId is required.PROPOSALAPPROVED: Get all the approved Requests by a user (relevant only for the TMC agent), userId is required.PROPOSALCANCELED: Get all the cancelled Requests for a user (relevant only for the TMC agent), userId is required.If no view value is sent, the default view ALL will be used. |
userId |
string |
- | Associated with a traveler view: the unique identifier of the Request owner to use when searching for Requests. Associated with an approver view: the unique identifier of the approver to user when searching for Requests. Associated with a TMC agent view, Required, the unique identifier of the TMC agent to use. This TMC agent user must have a default Travel Agency assigned in its profile corresponding to the Travel Agency assigned to the Requests |
start |
integer |
- | Pagination: index of the first record. Default: 0 |
limit |
integer |
- | Number of records to return per page. Default: 10. Maximum limit: 100, if higher value or digit value is set, a 400 error code will be displayed. |
approvedBefore |
dateTime |
yyyy-MM-dd'T'HH:mm:ss'Z' or yyyy-MM-dd |
Returns Requests that have been approved before the specified date and time. This search term can be used along with other search terms to narrow the results. The date and time should be in UTC. when time is missing it is defaulted to midnight. |
approvedAfter |
dateTime |
yyyy-MM-dd'T'HH:mm:ss'Z' or yyyy-MM-dd |
Returns Requests that have been approved after the specified date and time. This search term can be used along with other search terms to narrow the results. The date and time should be in UTC. When time is missing it is defaulted to midnight. |
modifiedBefore |
dateTime |
yyyy-MM-dd'T'HH:mm:ss'Z' or yyyy-MM-dd |
Returns Requests in which the associated dependents (Header, Expected expenses, Segments, Allocations, Attendees, Comments) were modified before the specified date and time. This search term can be used along with other search terms to narrow the results. The date and time should be in UTC. When time is missing it is defaulted to midnight. |
modifiedAfter |
dateTime |
yyyy-MM-dd'T'HH:mm:ss'Z' or yyyy-MM-dd |
Returns Requests in which the associated dependents (Header, Expected expenses, Segments, Allocations, Attendees, Comments) were modified after the specified date and time. This search term can be used along with other search terms to narrow the results. The date and time should be in UTC. When time is missing it is defaulted to midnight. |
sortField |
string |
- | The name of the field on which to sort. Supported values: startDate, approvalStatus, requestId. If no view value is sent, the default sortField startDate will be used. |
sortOrder |
string |
- | Sort order. Supported values: ASC, DESC. If no view value is sent, the default sortOrder DESC will be used. |
Payload
None.
HTTP Response
HTTP Status Codes
To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.
Payload
Example
HTTP Request
GET https://us.api.concursolutions.com/travelrequest/v4/requests?view=ALL&limit=10&start=0
Accept: application/json
Authorization: Bearer {token}
HTTP Response
200 OK
{
"data": [{
"href": "https://us.api.concursolutions.com/travelrequest/v4/requests/2B19A2438CD6664A9C44E0F4D39E870A",
"id": "2B19A2438CD6664A9C44E0F4D39E870A",
"approvalStatus": {
"code": "SUBMITTED",
"name": "Submitted & Pending Approval"
},
"approved": false,
"approver": {
"id": "86ac9588-5032-3fa7-b3cc-20e97d2d7146",
"firstName": "Jason",
"lastName": "McCafee"
},
"businessPurpose": "PMP Training in Nantes",
"canceledPostApproval": false,
"closed": false,
"comment": "Plane too early in the morning, if possible book Hotel and arrive the day before\n",
"creationDate": "2018-09-03T11:53:02.000Z",
"endDate": "2018-10-08",
"everSentBack": true,
"expenses": [],
"name": "PMP Training - OCTOBER",
"owner": {
"firstName": "John",
"id": "c0d9894b-98e2-48d5-86f9-1decde90dd15",
"lastName": "Doe"
},
"pendingApproval": true,
"requestId": "3AT7",
"startDate": "2018-10-08",
"startTime": "05:00",
"submitDate": "2018-09-03T11:55:00.000Z",
"totalApprovedAmount": {
"value": 213.06,
"currency": "USD"
},
"totalPostedAmount": {
"value": 213.06,
"currency": "USD"
},
"totalRemainingAmount": {
"value": 213.06,
"currency": "USD"
},
"type": {
"code": "TRAVEL",
"label": "Travel"
}
},
{
"href": "https://us.api.concursolutions.com/travelrequest/v4/requests/4CCBAE73F3E14346AE93253480F5C409",
"id": "4CCBAE73F3E14346AE93253480F5C409",
"approvalStatus": {
"code": "NOT_SUBMITTED",
"name": "Not Submitted"
},
"approved": false,
"businessPurpose": "Client meeting for project KIWI",
"canceledPostApproval": false,
"closed": false,
"comment": "Need to arrive the day before as meeting is in Company office early in the morning\n",
"creationDate": "2018-09-03T11:44:10.000Z",
"endDate": "2018-09-20",
"everSentBack": false,
"expenses": [],
"name": "Client meeting in Berlin",
"owner": {
"firstName": "John",
"id": "c0d9894b-98e2-48d5-86f9-1decde90dd15",
"lastName": "Doe"
},
"pendingApproval": false,
"requestId": "3AT6",
"startDate": "2018-09-18",
"startTime": "17:30",
"submitDate": "2018-09-03T11:49:32.000Z",
"totalApprovedAmount": {
"value": 478.56,
"currency": "USD"
},
"totalPostedAmount": {
"value": 478.56,
"currency": "USD"
},
"totalRemainingAmount": {
"value": 478.56,
"currency": "USD"
},
"type": {
"code": "TRAVEL",
"label": "Travel"
}
}
],
"operations": [{
"rel": "next",
"href": "https://us.api.concursolutions.com/travelrequest/v4/requests?view=ALL&limit=3&start=3"
},
{
"rel": "first",
"href": "https://us.api.concursolutions.com/travelrequest/v4/requests?view=ALL&limit=3&start=0"
},
{
"rel": "last",
"href": "https://us.api.concursolutions.com/travelrequest/v4/requests?view=ALL&limit=3&start=135"
}
]
}
Get the content of an existing Request
Scopes
travelrequest.write - Refer to Scope Usage for full details.
HTTP Request
URI Template
GET {datacenter}/travelrequest/v4/requests/{requestUuid}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
requestUuid |
string |
- | Required The unique identifier of the Request. |
userId |
string |
- | The unique identifier of the user getting the content of the Request. If empty when using a Company token the default system user will be assumed to perform the action. |
Payload
None.
HTTP Response
HTTP Status Codes
To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.
Payload
Request - The Request having {requestUuid} as unique identifier.
Example
HTTP Request
GET https://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2
Accept: application/json
Authorization: Bearer {token}
HTTP Response
200 OK
{
"href": "https://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2",
"id": "224AF3CDCC2A5244A37C72FA5770C6F2",
"approvalStatus": {
"code": "NOT_SUBMITTED",
"name": "Not Submitted"
},
"approved": false,
"businessPurpose": "Client meeting for project KIWI",
"canceledPostApproval": false,
"cashAdvances": {
"href": "https://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2/cashadvances",
"id": "224AF3CDCC2A5244A37C72FA5770C6F2",
"template": "https://us.api.concursolutions.com/travelrequest/v4/requests/{id}/cashadvances"
},
"closed": false,
"comment": "Need to arrive the day before for meeting in Company Office",
"comments": {
"href": "http://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2/comments",
"id": "224AF3CDCC2A5244A37C72FA5770C6F2",
"template": "http://us.api.concursolutions.com/travelrequest/v4/requests/{id}/comments"
},
"creationDate": "2018-05-25T07:31:33.000Z",
"custom1": {
"value": "Kick-off meeting for project KIWI"
},
"custom2": {
"code": "CEN1",
"value": "54F0CBD8833CB348BD45A6C7C621C951"
},
"custom3": {
"code": "CEN1PRO2",
"value": "441D6FC50766A044ACC07FF780F1BAD9"
},
"custom4": {
"code": "CLIENTPROJECT",
"value": "050BE16A7BF72948810AFDBC9069BD8E"
},
"endDate": "2018-07-17",
"endTime": "19:30",
"everSentBack": false,
"exceptions": {
"href": "https://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2/exceptions",
"id": "224AF3CDCC2A5244A37C72FA5770C6F2",
"template": "https://us.api.concursolutions.com/travelrequest/v4/requests/{id}/exceptions"
},
"expensePolicy": {
"id": "A6D42A825114472FAF402180E20B3751"
},
"expenses": [
{
"href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/B5FB8991E390474E875D6FD5BB1FDAF1",
"id": "B5FB8991E390474E875D6FD5BB1FDAF1",
"template": "https://us.api.concursolutions.com/travelrequest/v4/expenses/{id}"
},
{
"href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/D65BDBD5D980F6498D67A92B06A457B0",
"id": "D65BDBD5D980F6498D67A92B06A457B0",
"template": "hhttps://us.api.concursolutions.com/travelrequest/v4/expenses/{id}"
},
{
"href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/C286A46A2DDF984EA28E41CEA278667D",
"id": "C286A46A2DDF984EA28E41CEA278667D",
"template": "https://us.api.concursolutions.com/travelrequest/v4/expenses/{id}"
}
],
"lastModified": "2018-05-25T07:34:01.000Z",
"mainDestination": {
"countryCode": "DE",
"countrySubDivisionCode": "DE-BE",
"city": "Berlin, GERMANY",
"name": "Berlin, GERMANY"
},
"name": "Client meeting in Berlin - JULY",
"owner": {
"firstName": "John",
"id": "c0d9894b-98e2-48d5-86f9-1decde90dd15",
"lastName": "Doe"
},
"pendingApproval": false,
"policy": {
"id": "00497B95D8055849A1B217C8D05FFB86"
},
"requestId": "333T",
"startDate": "2018-07-15",
"startTime": "06:00",
"totalApprovedAmount": {
"value": 494.56,
"currency": "USD"
},
"totalPostedAmount": {
"value": 494.56,
"currency": "USD"
},
"totalRemainingAmount": {
"value": 494.56,
"currency": "USD"
},
"travelAgency": {
"href": "https://us.api.concursolutions.com/travelrequest/v4/travelagencies/2EC038D7C3CBBE4ABA0914425064D34F",
"id": "2EC038D7C3CBBE4ABA0914425064D34F",
"template": "https://us.api.concursolutions.com/travelrequest/v4/travelagencies/{id}"
},
"type": {
"code": "TRAVEL",
"label": "Travel"
},
"operations": [
{
"rel": "submit",
"href": "https://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2/submit"
}
]
}
Update the content of an existing Request
Update of the following fields is supported : comment, startDate, startTime, endDate, endTime, expensePolicy, name, businessPurpose, mainDestination, travelAgency, and custom fields. Other fields will be ignored.
This endpoint supports partial update. You may submit only the fields to update in the body, fields not present in the body will remain unchanged. To clear a field use the value null (without quotes).
id field is not mandatory in the payload, if provided the value must match the requestUuid parameter.
Scopes
travelrequest.write - Refer to Scope Usage for full details.
HTTP Request
URI Template
PUT {datacenter}/travelrequest/v4/requests/{requestUuid}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
requestUuid |
string |
- | Required The unique identifier of the Request. |
userId |
string |
- | The unique identifier of the user performing the update. Required when connecting with a Company token. If empty a 400, missingRequiredParam error code will be displayed. |
Payload
HTTP Response
HTTP Status Codes
To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.
Payload
Request - The Request having {requestUuid} as unique identifier after update.
Example
HTTP Request
PUT https://us.api.concursolutions.com/travelrequest/v4/requests/E82B0B803671004B9A5D952F34FBD01E
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}
{
"businessPurpose": "Trip to Lyon for company training - Modification of dates and Cost center + Custom Field",
"comment": "Company training requires to go to Lyon - Dates and service changed",
"custom1": {
"value": "Training part of IT Service"
},
"custom2": {
"value": "54F0CBD8833CB348BD45A6C7C621C951"
},
"custom3": {
"value": "441D6FC50766A044ACC07FF780F1BAD9"
},
"custom4": {
"value": "3F54AE68BA66EF49A5984E5197202A4D"
},
"endDate": "2018-07-09",
"endTime": "19:00",
"id": "053A479B3C9DD847B02A203C657AE26B",
"startDate": "2018-07-07",
"startTime": "06:15",
"name": "Company Training - JULY 2018",
"mainDestination": {
"city": "Lyon, FRANCE",
"countryCode": "FR",
"countrySubDivisionCode": "FR-69",
"name": "Lyon, FRANCE"
},
"policy": {
"id": "F4C8BD31CA9D4D6292795BE687EB9B2A"
},
"travelAgency": {
"id": "2EC038D7C3CBBE4ABA0914425064D34F"
}
}
HTTP Response
200 OK
{
"href": "https://us.api.concursolutions.com/travelrequest/v4/requests/053A479B3C9DD847B02A203C657AE26B",
"id": "053A479B3C9DD847B02A203C657AE26B",
"approvalStatus": {
"code": "NOT_SUBMITTED",
"name": "Not Submitted"
},
"approved": false,
"businessPurpose": "Trip to Lyon for company training - Modification of dates and Cost center + Custom Field",
"canceledPostApproval": false,
"closed": false,
"comment": "Company training requires to go to Lyon - Dates and service changed",
"creationDate": "2018-05-25T09:17:25.000Z",
"custom1": {
"value": "Training part of IT Service"
},
"custom2": {
"code": "CEN1",
"value": "54F0CBD8833CB348BD45A6C7C621C951"
},
"custom3": {
"code": "CEN1PRO2",
"value": "441D6FC50766A044ACC07FF780F1BAD9"
},
"custom4": {
"code": "TRAINING",
"value": "3F54AE68BA66EF49A5984E5197202A4D"
},
"endDate": "2018-07-09",
"endTime": "19:00",
"everSentBack": false,
"expenses": [],
"lastModified": "2018-05-25T09:24:34.000Z",
"mainDestination": {
"countryCode": "FR",
"countrySubDivisionCode": "FR-69",
"city": "Lyon, FRANCE",
"name": "Lyon, FRANCE"
},
"name": "Company Training - JULY 2018",
"owner": {
"firstName": "John",
"id": "c0d9894b-98e2-48d5-86f9-1decde90dd15",
"lastName": "Doe"
},
"pendingApproval": false,
"policy": {
"id": "F4C8BD31CA9D4D6292795BE687EB9B2A"
},
"requestId": "333X",
"startDate": "2018-07-07",
"startTime": "06:15",
"totalApprovedAmount": {
"value": 0,
"currency": "USD"
},
"totalPostedAmount": {
"value": 0,
"currency": "USD"
},
"totalRemainingAmount": {
"value": 0,
"currency": "USD"
},
"travelAgency": {
"href": "https://us.api.concursolutions.com/travelrequest/v4/travelagencies/2EC038D7C3CBBE4ABA0914425064D34F",
"id": "2EC038D7C3CBBE4ABA0914425064D34F",
"template": "https://us.api.concursolutions.com/travelrequest/v4/travelagencies/{id}"
},
"type": {
"code": "TRAVEL",
"label": "Travel"
},
"operations": [
{
"rel": "submit",
"href": "https://us.api.concursolutions.com/travelrequest/v4/requests/053A479B3C9DD847B02A203C657AE26B/submit"
}
]
}
Delete an existing Request
Scopes
travelrequest.write - Refer to Scope Usage for full details.
HTTP Request
URI Template
DELETE {datacenter}/travelrequest/v4/requests/{requestUuid}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
requestUuid |
string |
- | Required The unique identifier of the Request. |
userId |
string |
- | The unique identifier of the user performing the deletion. Required when connecting with a Company token. If empty a 400, missingRequiredParam error code will be displayed. |
Payload
None.
HTTP Response
Payload
None.
Example
HTTP Request
DELETE https://us.api.concursolutions.com/travelrequest/v4/requests/0D4DC4589D33AC4B9AF2E8B548C7AD2C
Accept: application/json
Authorization: Bearer {token}
HTTP Response
200 OK
true
Get the list of comments for an existing Request
Scopes
travelrequest.write - Refer to Scope Usage for full details.
HTTP Request
URI Template
GET {datacenter}/travelrequest/v4/requests/{requestUuid}/comments
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
requestUuid |
string |
- | Required The unique identifier of the Request. |
Payload
None.
HTTP Response
HTTP Status Codes
To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.
Payload
Example
HTTP Request
GET https://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2/comments
Accept: application/json
Authorization: Bearer {token}
HTTP Response
200 OK
[
{
"author": {
"firstName": "Steve",
"lastName": "Smith"
},
"creationDateTime": "2019-07-12T11:51:14.000Z",
"isLatest": true,
"value": "Please specify an amount less than 600 Euros"
},
{
"author": {
"firstName": "John",
"lastName": "Doe"
},
"creationDateTime": "2019-07-12T11:11:39.000Z",
"isLatest": false,
"value": "Please review the business meal excepted expense to confirm required amount"
}
]
Get the list of cash advances assigned to an existing Request
Scopes
travelrequest.write - Refer to Scope Usage for full details.
HTTP Request
URI Template
GET {datacenter}/travelrequest/v4/requests/{requestUuid}/cashadvances
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
requestUuid |
string |
- | Required The unique identifier of the Request. |
userId |
string |
- | The unique identifier of the user getting the list of the cash advances assigned to a Request. Required when connecting with a Company token. If empty, a 400 missingRequiredParam error code will be displayed. |
Payload
None.
HTTP Response
HTTP Status Codes
To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.
Payload
ResourceLink - The resource link leading to the created cash advance.
Example
HTTP Request
GET https://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2/cashadvances
Accept: application/json
Authorization: Bearer {token}
HTTP Response
200 OK
[
{
"href": "https://us.api.concursolutions.com/travelrequest/v4/cashadvances/EF3E237ACAA3C449B808BA75BDD049FA",
"id": "EF3E237ACAA3C449B808BA75BDD049FA",
"template": "https://us.api.concursolutions.com/travelrequest/v4/cashadvances/{id}"
},
{
"href": "https://us.api.concursolutions.com/travelrequest/v4/cashadvances/9DDAB28B89828A4497209062F4AF87D6",
"id": "9DDAB28B89828A4497209062F4AF87D6",
"template": "https://us.api.concursolutions.com/travelrequest/v4/cashadvances/{id}"
}
]
Get the list of exceptions linked to an existing Request
Scopes
travelrequest.write - Refer to Scope Usage for full details.
HTTP Request
URI Template
GET {datacenter}/travelrequest/v4/requests/{requestUuid}/exceptions
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
requestUuid |
string |
- | Required The unique identifier of the Request. |
userId |
string |
- | The unique identifier of the user getting the content of the exceptions. Required when connecting with a Company token. If empty, a 400 missingRequiredParam error code will be displayed. |
Payload
None.
HTTP Response
HTTP Status Codes
To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.
Payload
Example
HTTP Request
GET https://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2/exceptions
Accept: application/json
Authorization: Bearer {token}
HTTP Response
200 OK
[
{
"code": "CALWARN2",
"level": 1,
"message": "The requested Cash Advance exceeds the limit allowed by your company policy which is defined as the total of Daily Allowances (€0.00). Please update the requested amount accordingly.",
"isBlocking": false,
"source": {
"id": "DAF37B097DB82D4D9A15E9F3F7E460C9",
"href": "https://emea.api.concursolutions.com/v4/requests/DAF37B097DB82D4D9A15E9F3F7E460C9?compact=false",
"type": "HEADER"
},
"parameters": {}
}
]
Travel Request v4 - Endpoints - Schemas
Schema
- Request
- Amount
- ApprovalStatus
- Cash Advance
- Cash Advance Approval Status
- Comments
- Customfield
- Employee
- Exceptions
- Exception Source
- Link
- List of Request
- List of Request Policies
- Location
- ResourceLink
- RequestLink
- Request Policy
- Request Type
- Expected Expense
- Allocation
- Exchange Rate
- Expense Type
- List Item Field
- Segment Leg
- Segment Type
- Travel Agency
- Travel Allowance
- Trip Data
- Vendor
Request
| Name | Type | Format | Description |
|---|---|---|---|
approvalLimitDate |
timestamp |
[RFC 3339] yyyy-MM-dd'T'HH:mm:ss.SSS'Z' |
The date by which the Request must be approved. This element appears only when integrated with Concur Travel. |
approvalStatus |
object |
Approval Status |
The approval status of the Request. |
approved |
boolean |
- | Indicates whether this Request is approved. |
approver |
object |
Employee |
The approver to whom the Request was sent. |
authorizedDate |
timestamp |
[RFC 3339] yyyy-MM-dd'T'HH:mm:ss.SSS'Z' |
For approved Request, the date at which the approval process was completed. |
businessPurpose |
string |
- | The business purpose of the Request. |
canceledPostApproval |
boolean |
- | Indicates whether this Request was canceledPostApproval. |
cashAdvances |
object |
ResourceLink |
The list of cash advances for this Request. |
closed |
boolean |
- | Indicates whether this Request is closed. |
comment |
string |
- | The last comment attached to this Request. |
comments |
object |
ResourceLink |
The list of comments for this Request. |
creationDate |
timestamp |
[RFC 3339] yyyy-MM-dd'T'HH:mm:ss.SSS'Z' |
The date the Request was created. |
custom1 to custom20 |
object |
CustomField |
The details from the Custom fields. These fields may not have data, depending on the configuration. |
endDate |
date |
[ISO 8601] yyyy-MM-dd |
The end date of the Request. |
endTime |
time |
[ISO 8601] yyyy-MM-dd |
The end time of the Request. |
everSentBack |
boolean |
- | Indicates whether the Request has ever been sent back to the employee. |
exceptions |
object |
ResourceLink |
The list of exceptions that have been raised to this Request. |
expenses |
array |
ResourceLink |
Expected expenses attached to this Request. |
extensionOf |
object |
RequestLink |
The Request that this Request is an extension of, or addendum to. |
highestExceptionLevel |
string |
- | The highest level of exception contained in this Request. Supported values: WARNING, ERROR, and NONE |
href |
string |
[RFC 3986] | Hyperlink to the resource for this Request. |
id |
string |
- | The unique identifier of the Request. |
lastModified |
timestamp |
[RFC 3339] yyyy-MM-dd'T'HH:mm:ss.SSS'Z' |
The date the Request was last modified. |
mainDestination |
object |
Location |
The main destination of the Request. |
name |
string |
- | The name of the Request. |
owner |
object |
Employee |
The employee who owns the Request. |
pendingApproval |
boolean |
- | Indicates whether this Request is pending approval. |
policy |
object |
ResourceLink |
The policy that applies to the Request. |
requestId |
string |
4 to 6 alphanumeric characters | The public key of the Request (unique per customer). |
startDate |
date |
[ISO 8601] yyyy-MM-dd |
The start date of the Request. |
startTime |
time |
[ISO 8601] yyyy-MM-dd |
The start time of the Request. |
submitDate |
timestamp |
[RFC 3339] yyyy-MM-dd'T'HH:mm:ss.SSS'Z' |
The date the Request was submitted (last submit date in case of recall). |
totalApprovedAmount |
object |
Amount |
The total amount of approved expected expenses in the Request, expressed in the reimbursement currency of the employee at the time they created the Request. |
totalPostedAmount |
object |
Amount |
The total amount of the Request, expressed in the reimbursement currency of the employee at the time they created the Request. |
totalRemainingAmount |
object |
Amount |
The total amount not included in an Expense report, expressed in the reimbursement currency of the employee at the time they created the Request. |
travelAgency |
object |
ResourceLink |
The travel agency office that is managing the trip associated to this Request. |
operations |
array |
Link |
Links to operations available for the Request, depends on the current workflow status. |
type |
object |
RequestType |
The type of the Request, inherited from the Request Policy Type. |
Amount
| Name | Type | Format | Description |
|---|---|---|---|
value |
number |
- | Required The amount in the defined currency. |
currency |
string |
[ISO 4217:2015] | Required The 3-letter ISO 4217 code for the currency in which the amount is expressed. |
Approval Status
| Name | Type | Format | Description |
|---|---|---|---|
code |
string |
- | The code for the approval status of the Request. Supported values: NOT_SUBMITTED, SUBMITTED, APPROVED, CANCELED, or SENTBACK |
name |
string |
- | The approval status of the Request in the current user's language. |
Cash Advance
| Name | Type | Format | Description |
|---|---|---|---|
amountRequested |
object |
Amount |
The amount of the cash advance in the Request, expressed in the currency of the requested cash advance. For the Cash Advance detail endpoint only, the Amount schema will contain an additional amount field for feature parity purpose with the new planned Cash Advance API part of the cash advance service. The value field will be soon deprecated, it is highly recommended to rely on the amount field in that case. |
approvalStatus |
object |
Cash Advance Approval Status |
The approval status of the cash advance. |
cashAdvanceId |
string |
- | The unique identifier of the cash advance. |
comment |
string |
- | The last comment related to this cash advance. |
exchangeRate |
object |
Exchange Rate |
The exchange rate that applies to the cash advance. |
issueDate |
timestamp |
[RFC 3339] yyyy-MM-dd'T'HH:mm:ss.SSS |
The date the cash advance was issued. |
requestDate |
timestamp |
[RFC 3339] yyyy-MM-dd'T'HH:mm:ss.SSS |
The date the cash advance was submitted (last submit date in case of recall). |
Cash Advance Approval Status
| Name | Type | Format | Description |
|---|---|---|---|
code |
string |
- | The code for the approval status of the cash advance. Supported values: C_PEND, C_APPR, C_COMP, C_FILE, C_ISSU, C_NISU, C_NOTF, C_PECA, or C_REJE |
name |
string |
- | The approval status of the cash advance in the current user's language. |
Comments
| Name | Type | Format | Description |
|---|---|---|---|
author |
object |
Employee |
The employee who has created the comment in the expected expense. |
creationDate |
timestamp |
[RFC 3339] yyyy-MM-dd'T'HH:mm:ss.SSS |
Creation date of the comment. |
isLatest |
boolean |
- | If true, the comment has been edited since the last workflow transition. |
value |
string |
- | The value of the comment. |
CustomField
| Name | Type | Format | Description |
|---|---|---|---|
code |
string |
- | The short code for the list item. For non-list fields, this value will be blank. |
value |
string |
- | The value of the non-list item. For list fields, this is the unique id of the list item. |
href |
string |
- | The link to get this list item on the list service. Empty for non-list items. |
Retrieving the listItemId requires to call the List API, which is currently being worked on for externalisation. In the meantime, to fill in a custom list item for the creation of a Request or an Expected Expense, clients may use one of the following workaround:
* Use the copy down configuration feature to update custom fields from the Employee profile to the Request header, and from the Request header to the Expected expense.
* For a limited number of list items that are part of a custom field, a Request containing those values in the related custom fields may be manually created. The list item unique id will then be retrieved by calling the get detail of this Request. The same process is used for all list items values of the list.
Employee
| Name | Type | Format | Description |
|---|---|---|---|
firstName |
string |
- | The first name of the employee. |
href |
string |
[RFC 3986] | Hyperlink to the resource. |
id |
string |
[RFC 4122] | Unique identifier of the related object. |
lastName |
string |
- | The last name of the employee. |
middleInitial |
string |
- | The middle initial of the employee. |
template |
string |
- | Hyperlink template to the resource. |
Exceptions
| Name | Type | Format | Description |
|---|---|---|---|
code |
string |
- | The system exception code defined for the exception. Example: BADCODE |
isBlocking |
boolean |
- | Defines whether the exception will prevent the Request from being submitted. |
level |
integer |
- | The numeric level associated with the exception. Example: 99 |
message |
string |
- | The user facing message defined for the exception. |
source |
array |
Exception source |
The source that has raised the exception. |
parameters |
map |
missingFields: array of missing field labelsmissingFieldsIds: array of missing field ids |
For missing fields exceptions, additional values giving more label and ids of the missing fields. Example : parameters : { "missingFields" : ["Request Name", "Purpose"], "missingFieldsIds" : [ "Name", "Purpose" ] } |
Exception Source
| Name | Type | Format | Description |
|---|---|---|---|
href |
string |
[RFC 3986] | Hyperlink to the resource. |
id |
string |
[RFC 4122] | Unique identifier of the source. |
type |
string |
- | Defines the type of the source. Supported values: ALLOCATION, CASH_ADVANCE, EXPENSE, and HEADER |
Link
| Name | Type | Format | Description |
|---|---|---|---|
rel |
string |
[RFC 5988] | Relation type as defined by the server. There are registered relation types listed in RFC 5988 6.2.2. Initial Registry Contents including pagination relation types of next, prev, first and last. |
href |
string |
[RFC 3986] | Hyperlink to the resource. |
List of Request
| Name | Type | Format | Description |
|---|---|---|---|
data |
array |
Request |
List of Requests in the page requested. |
operations |
array |
Link | Links to next, prev, first and last pages. |
List of Request Policies
| Name | Type | Format | Description |
|---|---|---|---|
| - | array |
Request Policy |
List of active Requests policies for a given user. |
Location
| Name | Type | Format | Description |
|---|---|---|---|
city |
string |
- | Required for all city location type (not airport, or rail station - except for STD location type) The city name of the location. Note: STD location type for rail is considered as a city location type, city and countryCode fields are required in that case. |
countryCode |
string |
[ISO 3166-1] | Required if city or name is used The ISO 3166-1 country code. |
countrySubDivisionCode |
string |
[ISO 3166-2] | The ISO 3166-2 country sub code. |
iataCode |
string |
- | Required if air is used The IATA code of an airport location. |
id |
string |
- | The id of the location. |
latitude |
number |
- | The latitude of the location. |
locationCode |
string |
- | Required if rail is used with RAIL_xx locationType The code of the location. Optional for segments based on city locations (will be required in case of duplicate locations within database). |
locationType |
string |
- | Required if rail is used The type of the location. |
longitude |
number |
- | The longitude of the location. |
name |
string |
- | The name of the location. Always provide the countryCode value in addition to the name. |
Below are the different node expected in the POST endpoints by location type (City, Rail station, or Airport) - example for endLocation field:
Airport
json
"endLocation": {
"city": "Moscow",
"name": "Sheremetyevo",
"countryCode": "RU",
"iataCode": "SOV"
}
City
json
"endLocation": {
"city": "Vienna",
"countryCode": "AT"
}
Rail station (locationCode exists, locationType depends of rail provider)
json
"endLocation": {
"name": "MARSEILLE ST CHARLES",
"countryCode": "FR",
"locationCode": "FRMSC",
"locationType": "RAIL_2C"
}
Location types for Rail :
| Location Type | Railway company |
|---|---|
RAIL_0Z |
Swiss Federal Railways |
RAIL_2A |
Deutsche Bahn AG |
RAIL_2C |
SNCF |
RAIL_2H |
Thalys International |
RAIL_2R |
VIA Rail Canada Inc. |
RAIL_2V |
Amtrak |
RAIL_9F |
Eurostar International Limited |
RAIL_XH |
China Railway |
RAIL_Z0 |
UK Rail |
STD |
Standard locations |
ResourceLink
| Name | Type | Format | Description |
|---|---|---|---|
href |
string |
[RFC 3986] | Hyperlink to the resource. |
id |
string |
[RFC 4122] | Unique identifier of the related object. |
template |
string |
- | Hyperlink template to the resource. |
RequestLink
| Name | Type | Format | Description |
|---|---|---|---|
requestId |
string |
4 to 6 alphanumeric characters | The public key of the Request (unique per customer). |
Request Policy
| Name | Type | Format | Description |
|---|---|---|---|
href |
string |
[RFC 3986] | Hyperlink to the resource for this Request policy. |
id |
string |
- | The Request policy unique identifier. |
name |
string |
- | The name of the Request policy. |
Request Type
| Name | Type | Format | Description |
|---|---|---|---|
code |
string |
- | The code of the type inherited from the Request Policy type. Possible values: Authorization, Cash Advance, Travel. |
label |
string |
- | The label of the type inherited from the Request Policy Type. |
Expected Expense
| Name | Type | Format | Description |
|---|---|---|---|
allocations |
object |
Allocation |
The details of the allocations for this expected expense. |
approvedAmount |
object |
Amount |
The approved amount of the expected expense entry, in the transaction currency of the Request. |
budgetAccrualDate |
timestamp |
[RFC 3339] yyyy-MM-dd'T'HH:mm:ss.SSS'Z' |
The date to determine which budgets are affected. |
businessPurpose |
string |
- | The business purpose of the Request entry. |
comments |
object |
ResourceLink |
The list of comments for this expected expense. |
custom1 to custom40 |
object |
CustomField |
The details from the Custom fields. These fields may not have data, depending on the configuration. |
exchangeRate |
object |
Exchange Rate |
The exchange rate that applies to the entry. |
expenseType |
object |
Expense Type |
The expense type of the entry. Required for expected expenses, automatically set for segments depending on the SegmentType code. |
href |
string |
[RFC 3986] | Hyperlink to the resource for this Request entry. |
id |
string |
- | The unique identifier of the expected expense entry. |
lastComment |
string |
- | The last comment (most recent) of the expected expense entry. |
lastModifiedDate |
timestamp |
[RFC 3339] | The date when this expected expense was last modified. |
location |
object |
Location |
The location of the expected expense entry. |
orgUnit1 to orgUnit6 |
object |
Amount |
The details from the Custom fields. These fields may not have data, depending on the configuration. |
postedAmount |
object |
Amount |
The posted amount of the expected expense entry, in the transaction currency of the Request. |
parentRequest |
object |
ResourceLink |
The parent Request of the expected expense. |
remainingAmount |
object |
Amount |
The remaining amount of the expected expense entry, in the transaction currency of the Request. |
source |
enum |
- | The source that created the expected expense. Supported values: CASH_ADVANCE or TRAVEL_ALLOWANCE. This field will be empty in any other case |
transactionAmount |
object |
Amount |
Required The amount of the expected expense entry, in the transaction currency paid to the vendor. |
transactionDate |
timestamp |
[RFC 3339] yyyy-MM-dd'T'HH:mm:ss.SSS'Z' |
Required The date of the transaction. |
travelAllowance |
object |
Travel Allowance |
The Travel allowance. |
tripData |
object |
Trip Data |
The description of the trip. |
vendor |
object |
Vendor |
The vendor of the expected expense entry. |
Allocation
| Name | Type | Format | Description |
|---|---|---|---|
allocationAmount |
object |
Amount |
The amount of the allocation calculated with the percentage value multiplied by the transaction amount on the expected expense. This amount is given in the transaction's currency and rounded to eight digits after the decimal point. |
approvedAmount |
object |
Amount |
The amount of the allocation calculated with the percentage value multiplied by the approved amount on the expected expense. This amount is given in the user's currency and rounded to eight digits after the decimal point. |
allocationId |
string |
- | The unique allocation identifier. |
custom1 to custom20 |
object |
CustomField |
The details from the Custom fields. These fields may not have data, depending on the configuration. |
expenseId |
string |
- | The unique identifier of the expected expense associated with the allocation. |
percentEdited |
boolean |
- | Whether the allocation percent has been edited. |
percentage |
number |
- | The percentage of the total expected expense that this allocation represents. |
postedAmount |
object |
Amount |
The amount of the allocation calculated with the percentage value multiplied by the posted amount on the expected expense. This amount is given in the user's currency and rounded to eight digits after the decimal point. |
systemAllocation |
boolean |
- | Whether the allocation is a system allocation, usually hidden from the user. If displayed to the user, should be read-only. |
Exchange Rate
| Name | Type | Format | Description |
|---|---|---|---|
operation |
string |
- | Exchange rate operation. Supported values: MULTIPLY, DIVIDE |
value |
number |
- | Exchange rate value. |
Expense Type
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
- | Required Unique identifier of the expense type. |
name |
string |
- | Name of the expense type. |
List Item Field
| Name | Type | Format | Description |
|---|---|---|---|
code |
string |
- | The short code of the list item. |
value |
string |
- | Unique identifier of the list item. |
href |
string |
[RFC 3986] | Hyperlink to the resource for the list item. |
Segment Leg
| Name | Type | Format | Description |
|---|---|---|---|
class |
list |
List Item Field |
The booking class of the segment leg. |
classOfService |
string |
- | The class of service of the segment leg. For example, in the case of an air segment, this field would contain the one-letter booking code: Y for economy class, or F for first class. |
comment |
string |
- | Contains the last comment saved in this segment leg. |
custom1 to custom40 |
object |
CustomField |
The details from the Custom fields. These fields may not have data, depending on the configuration. |
endDate |
date |
[ISO 8601] YYYY-MM-DD |
The date of the end of this segment leg. It represents the arrival date of AIRFR and TRAIN segments, check out date for HOTEL, or drop off for CARRT. |
endLocation |
object |
ResourceLink |
The location where this segment leg arrives. For example, the arrival location for an air segment. |
endLocationDetail |
string |
- | Details about the end location. This would contain details about the name of a hotel, or some details about a car rental agency for example. |
endTime |
time |
[ISO 8601] HH:MM |
The time for the end of this segment leg. |
id |
string |
- | The unique identifier of the segment leg. |
returnLeg |
boolean |
- | Indicates whether this leg is the return leg of a round trip. In case of a ROUND_TRIP, if not explicitly set, the second segment leg will be considered as the return leg. |
startDate |
date |
[ISO 8601] YYYY-MM-DD |
The date of the beginning of this segment leg. |
startLocation |
object |
ResourceLink |
The start location of this segment leg. This would be the departure location for an air segment for example. |
startLocationDetail |
string |
- | Details about the start location. This would contain details about the name of a hotel, or some details about a car rental agency for example. |
startTime |
time |
[ISO 8601] HH:MM |
The time for the beginning of this segment leg. |
segmentLocator |
string |
- | This is the identifier for Concur Travel segments (if applicable). |
vendorName |
string |
- | Contains the vendor description of the segment leg. |
Segment Type
| Name | Type | Format | Description |
|---|---|---|---|
category |
enum |
- | Describes the category of this segment type. Supported values: REQ_SEG_AIRFR, REQ_SEG_CARRT, REQ_SEG_HOTEL, REQ_SEG_LIMOF, REQ_SEG_RAILF, REQ_SEG_TAXIF, REQ_SEG_MISC, REQ_SEG_PARKG, REQ_SEG_DININ, REQ_SEG_EVENT |
code |
string |
- | Required The code of the segment type. Supported values: AIRFR, CARRT, HOTEL, LIMOF, RAILF, TAXIF, MISC, PARKG, DININ, EVENT or custom codes |
It can be REQ_SEG_AIRFR / AIRFR for a regular air segment, or REQ_SEG_AIRFR / 10325 for a custom air segment.
Example:
{
"category": "REQ_SEG_AIRFR",
"code": "AIRFR"
}
Travel Agency
| Name | Type | Format | Description |
|---|---|---|---|
emailAddress |
string |
- | The travel agency email address. |
id |
string |
- | The travel agency unique identifier. |
name |
string |
- | The travel agency office name. |
proposalType |
string |
- | The travel agency proposal type. Supported values: CWTF, AEBT, API |
Travel Allowance
| Name | Type | Format | Description |
|---|---|---|---|
dailyTravelAllowanceId |
string |
- | The fixed daily travel allowance id associated with the expected expense. |
Trip Data
| Name | Type | Format | Description |
|---|---|---|---|
agencyBooked |
boolean |
- | If true, this travel is (or has to be) handled by a travel agency. |
legs |
list |
Segment Leg |
The list of the legs of the travel. |
tripType |
string |
- | Indicates the type of this trip. Supported values: ONE_WAY, ROUND_TRIP, or MULTI_STOPS. If not provided, will be detected from the given legs. |
segmentType |
object |
Segment Type |
Required The type of the segment. |
selfBooked |
boolean |
- | If true, this travel has been reserved by Concur Travel, or if Concur Travel has retrieved the trip information in the GDS. |
Vendor
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
- | The vendor identifier of the entry. |
name |
string |
- | The vendor description of the entry. |
Travel Request v4 - Travel Agency Resources
Manage the configuration for Travel Agencies integrated with Concur Request.
Get the description of a Travel Agency
Scopes
travelrequest.write - Refer to Scope Usage for full details.
HTTP Request
URI Template
GET {datacenter}/travelrequest/v4/travelagencies/{agencyUuid}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
agencyUuid |
string |
- | Required The unique identifier of the Travel Agency. |
Payload
None
HTTP Response
HTTP Status Codes
To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.
Payload
Example
HTTP Request
GET https://us.api.concursolutions.com/travelrequest/v4/travelagencies/86B720AF168F1C4CA52E37AC710E897B
Accept: application/json
Authorization: Bearer {token}
HTTP Response
200 OK
{
"href": "https://us.api.concursolutions.com/travelrequest/v4/travelagencies/86B720AF168F1C4CA52E37AC710E897B",
"id": "2EC038D7C3CBBE4ABA0914425064D34F",
"emailAddress": "agency-email@agencyname.com",
"name": "myCompanyAgency"
}
Travel Request v4 - Workflow Resources
Manage workflow transitions for a Request.
Move an existing Request in the approval workflow
Scopes
travelrequest.write - Refer to Scope Usage for full details.
HTTP Request
The HATEOAS links for actions available given the current user and state are listed in the operations of the Request resource.
Traveler actions
* submit: initiate the approval workflow.
* recall: get back the Request, usually to modify the content.
* cancel: cancel the Request and attached itineraries.
* close: archive the Request.
* reopen: get back an archived Request.
Non traveler actions (Approver / Processor / External Validation / TMC Agent)
approve: move the Request to the next approval step.sendback: reject the Request and send back to the traveler.
URI Template
POST {datacenter}/travelrequest/v4/requests/{requestUuid}/{action}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
requestUuid |
string |
- | Required The unique identifier of the Request. |
action |
string |
- | Required The state transition to be executed. Supported values: submit, approve, recall, sendback, cancel, close, or reopen |
comment |
string |
- | Only works with when the workflow action is sendback. This comment is visible wherever Request comments are available to the employee, approver, and/or Request administrator. |
userId |
string |
- | The unique identifier of the user performing the status transition. Required when connecting with a Company token for traveler actions only. If empty, a 400 missingRequiredParam error code will be displayed. For non traveler actions, if not provided, "System, Concur" will be displayed in the Audit Trail of the Request. |
companyID |
string |
- | The unique identifier of the company. |
Payload
None, except when the workflow action is sendback where an optional comment may be submitted
{ "comment" : "My Comment" }
This comment is visible wherever Request comments are available to the employee, approver, and/or Request administrator.
HTTP Response
HTTP Status Codes
To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.
Payload
Request - The Request having {requestUuid} as unique identifier.
Example
HTTP Request
POST https://us.api.concursolutions.com/travelrequest/v4/requests/053A479B3C9DD847B02A203C657AE26B/submit
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}
HTTP Response
200 OK
{
"href": "https://us.api.concursolutions.com/travelrequest/v4/requests/053A479B3C9DD847B02A203C657AE26B",
"id": "053A479B3C9DD847B02A203C657AE26B",
"approvalStatus": {
"code": "SUBMITTED",
"name": "Submitted & Pending Approval"
},
"approved": false,
"businessPurpose": "Trip to Lyon for company training - Modification of dates and Cost center + Custom Field",
"canceledPostApproval": false,
"closed": false,
"creationDate": "2018-05-25T09:17:25.000Z",
"custom1": {
"value": "Training part of IT Service"
},
"custom2": {
"code": "CEN1",
"value": "54F0CBD8833CB348BD45A6C7C621C951"
},
"custom3": {
"code": "CEN1PRO2",
"value": "441D6FC50766A044ACC07FF780F1BAD9"
},
"custom4": {
"code": "TRAINING",
"value": "3F54AE68BA66EF49A5984E5197202A4D"
},
"endDate": "2018-07-09",
"endTime": "19:00",
"everSentBack": false,
"expenses": [
{
"href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/47C8AD9E382B5143BB54DC3090577C60",
"id": "47C8AD9E382B5143BB54DC3090577C60",
"template": "https://us.api.concursolutions.com/travelrequest/v4/expenses/{id}"
}
],
"lastModified": "2018-05-25T09:38:02.000Z",
"mainDestination": {
"countryCode": "FR",
"countrySubDivisionCode": "FR-69",
"city": "Lyon, FRANCE",
"name": "Lyon, FRANCE"
},
"name": "Company Training - JULY 2018",
"owner": {
"firstName": "John",
"id": "c0d9894b-98e2-48d5-86f9-1decde90dd15",
"lastName": "Doe"
},
"pendingApproval": true,
"policy": {
"id": "F4C8BD31CA9D4D6292795BE687EB9B2A"
},
"requestId": "333X",
"startDate": "2018-07-07",
"startTime": "06:15",
"submitDate": "2018-05-25T09:38:02.000Z",
"totalApprovedAmount": {
"value": 123.56,
"currency": "USD"
},
"totalPostedAmount": {
"value": 123.56,
"currency": "USD"
},
"totalRemainingAmount": {
"value": 123.56,
"currency": "USD"
},
"travelAgency": {
"href": "https://us.api.concursolutions.com/travelrequest/v4/travelagencies/2EC038D7C3CBBE4ABA0914425064D34F",
"id": "2EC038D7C3CBBE4ABA0914425064D34F",
"template": "https://us.api.concursolutions.com/travelrequest/v4/travelagencies/{id}"
},
"operations": [
{
"rel": "recall",
"href": "https://us.api.concursolutions.com/travelrequest/v4/requests/053A479B3C9DD847B02A203C657AE26B/recall"
},
{
"rel": "cancel",
"href": "https://us.api.concursolutions.com/travelrequest/v4/requests/053A479B3C9DD847B02A203C657AE26B/cancel"
}
]
}
Travel Request v4 - Getting Started
Concur Request automates the spend request and approval process for both travel and everyday expenses, giving you the data you need to accurately track and better control spending. By increasing visibility into planned expenses and up-to-date budget data, you can make strategic spending decisions before any spending actually occurs. The Request API provides many possibilities, particularly Requests creation and transition into the approval workflow.
Version 4.0 of Request API works only with the new Authentication API.
Getting Started
- Overview
- Prior Versions
- Process Flow
- Products and Editions
- Scope Usage
- Dependencies
- Access Token Usage
Overview
The Request v4 API exposes five different resources:
| Resource | Description |
|---|---|
| Request | You can read, create, update or delete a Request and get the list of existing Requests. |
| Workflow | You can perform action in the approval workflow of a Request (submit, approve, cancel...) |
| Expected Expense | You can read, create, update or delete an expected expense, and get the list of expected Expenses for a specific Request. |
| Request Policy | You can get the list of existing Request policies. |
| Travel Agency | You can get the description of a Travel Agency office. |
These resources are used to manage documents used for pre-spend authorizations within Concur Request.
Prior Versions
Process Flow

Products and Editions
- Concur Request Professional Edition
- Concur Request Standard Edition
Scope Usage
| Name | Description | Endpoint |
|---|---|---|
travelrequest.write |
Read and write Requests | GET, POST, PUT, DELETE |
Dependencies
SAP Concur clients must purchase Concur Request in order to use this API. This API may require for some use cases to consume the following additional SAP Concur APIs:
- User profile, to retrieve the
userId- required in most of the endpoints when accessed via a Company Token. - [List], to retrieve the
listItemId- required in the management of custom fields related to list items. Currently in externalisation process, please liaise with List API owner team for further update.
Access Token Usage
This API supports both company level and user level access tokens.
Company Access Token
- The
userIdparameter is required to provide the user identity of who made the API call. - Does not have an associated role.
User Access Token
- The
userIdparameter is not required. - Requires the Web Service Admin role to call the API.
Travel Request v4 - HTTP Status Codes
| HTTP Status Code | Response Body | Description |
|---|---|---|
| 200 OK | - | Your GET request succeeded. |
| 201 Created | - | Your POST request succeeded. |
| 400 Bad Request | badParam the request has bad parameter(s) {requestName} |
The name of the request doesn't have the expected format |
| - | invalidJson invalid json structure |
An input JSON structure couldn't be parsed |
| - | invalidDate error while parsing date value {dateValue} |
A date or datetime value couldn't be parsed |
| - | invalidUuid for concur-correlationid {correlationId} |
The concur correlation id of the request is not a valid UUID |
| - | invalidUuid {requestName} |
The name of the request doesn't have the expected format |
| - | invalidLocation The location cannot be resolved, please provide either {iataCode} or {countryCode} and {cityName} |
Required location input is missing |
| - | invalidLocation The location cannot be resolved, no location found for iataCode={iataCode} |
No location found matching the iataCode provided |
| - | invalidLocation The location cannot be resolved, no city found for countryCode={countryCode}, cityName={cityName} and locationCode={locationCode} |
No location found matching the country code, city name and location code provided |
| - | severalLocationsMatch The location cannot be resolved, multiple locations available for countryCode={countryCode} and cityName={cityName}. Please provide a locationCode from the possible matches |
Multiple locations found matching the country code and city name provided, location code is required. |
| - | invalidPolicy invalid policy id |
|
| - | listValidationError validation of list items failed |
|
| - | missingRequiredField at least 1 required field has an empty value |
A request with no value on a mandatory field has been submitted |
| - | blockingException at least 1 blocking exception |
A request with a blocking exception has been submitted |
| - | multiLegNotAllowed cannot save a multi leg, multi-leg is not enabled for this entity |
The multi leg support is not allowed for the entity |
| - | reportTemplateNotFound failed to retrieve report template |
The multi leg support is not allowed for the entity |
| - | unsupportedParam the request has unsupported parameter(s) |
Some parameter(s) of the request are not supported |
| - | missingRequiredParam the request is missing required parameter(s) |
The request is missing some required parameter(s) |
| - | companyNotFound the company for this request has not been found |
The company for this request has not been found |
| - | userNotFound user {id} not found |
The user Id for this request has not been found |
| - | invalidUuid invalid {Uuid} for the userId |
The unique identifier for this userId is not valid |
| - | - Limit must be less than or equal to 100 |
limit must be less than or equal to 100 |
| - | - Limit must be greater than or equal to 1 |
limit must be greater than or equal to 1 |
| - | - Limit must contains only digits |
Limit must contains only digits |
| 401 Unauthorized | invalidUser the request's user is invalid |
invalid or non existent authorization HTTP header |
| 403 Forbidden | permissionDenied permission denied |
User approving their own Request, or without approver/processor role |
| - | requestStatusNotApproved the Request is not approved or canceled after approval |
|
| - | userIsNotAllowed user is not allowed to access this resource |
|
| - | requestStartDateInTheFuture expense report cannot be create from an approved Request before Request start |
|
| - | publicApiNotAllowed entity is not allowed to access this resource |
|
| - | publicApiNotAllowed this resource is not public |
|
| - | CASH_ADVANCE_CANNOT_SUBMIT_AS_DELEGATE |
The cash advance cannot be submitted by the delegate. |
| - | CASH_ADVANCE_CANNOT_APPROVE_OWN_CA |
You cannot approve your own cash advance. |
| 404 Not Found | notFound resource not found |
You tried to get a non-existing request |
| 408 Request Timeout | timeOut timeout has occurred |
|
| 409 Conflict | NO_APPROVER No approver was found. |
You must identify an approver before the request moves on to the next workflow step. |
| - | NO_APPROVER_NOT_EDITABLE_STEP |
There are no approvers defined in your workflow. Contact your Expense administrator for assistance. |
| - | NO_APPROVER_CHANGE_MY_INFO |
Missing the required approver for next workflow step. You may be able to select an approver; otherwise contact your Administrator for assistance. |
| - | NO_AUTH_APPROVERS |
This request cannot be sent to the next approver. This workflow step must be approved by a specialised approver called an Authorised Approver. There are no Authorised Approvers defined. Please contact your Request administrator for assistance. |
| - | REVIEW_APPROVAL_FLOW_APPROVER |
Review approvers in the workflow. |
| - | APPROVER_CUM_REPORTOWNER |
You cannot send this request to this approver since this person created this request. |
| - | APPROVER_CUM_REPORTOWNER_EDITABLE |
Your workflow is configured such that the request would come back to the request owner during some step. Please contact your Employee Administrator to change the approvers. |
| - | INVALID_AUTH_APPROVER |
This request cannot proceed without an approver type of Authorised Approver. Select an approver who is an Authorised Approver before proceeding. |
| - | CONFIG_INVALID_NEXT_STEP |
You must identify an approver before the request moves on to the next workflow step. |
| - | STEP_EXIT_BLOCKING_BY_EXCEPTION |
One or more blocking exceptions are preventing approval submission. Resolve the exception before proceeding. |
| - | CASH_ADVANCE_SUBMIT_GENERIC |
Cash Advance Status Change: Failure |
| - | CASH_ADVANCE_SUBMIT_ALREADY_SUBMITTED |
The cash advance has already been submitted and cannot be submitted again. |
| - | CASH_ADVANCE_CONFIG_INVALID_NEXT_STEP |
Cash Advance: You must identify an approver before the request moves on to the next workflow step |
| - | CASH_ADVANCE_APPROVER_CUM_REPORTOWNER |
Cash Advance: You cannot send this request to this approver since this person created this request. |
| - | CASH_ADVANCE_APPROVER_CUM_REPORTOWNER_IS_EDITABLE_BY |
Cash Advance: Your workflow is configured such that the claim would come back to the claim owner during some step. Please contact your Employee Administrator to change the approvers. |
| - | CASH_ADVANCE_INVALID_AUTH_APPROVER |
Cash Advance: This request cannot be sent to the next approver. This workflow step must be approved by a specialised approver called an Authorised Approver. The selected approver is not an Authorised Approver. Select another approver. |
| - | CASH_ADVANCE_NO_APPROVER |
Cash Advance: You must identify an approver before the request moves on to the next workflow step. |
| - | CASH_ADVANCE_NO_APPROVER_CHANGE_MY_INFO |
Cash Advance: Missing the required approver for the next workflow step. Contact your Expense administrator for assistance. |
| - | CASH_ADVANCE_NOT_AN_APPROVER |
Cash Advance: This request cannot be sent to the next approver because the selected approver is no longer authorised to approve requests. Please select another approver. |
| - | CASH_ADVANCE_REVIEW_APPROVAL_FLOW_APPROVER |
Cash Advance: Review Approvers in the workflow. |
| 500 Internal Server Error | createReportError error while creating an expense report |
|
| - | internalServerError internal server error |
|
| - | associateReportError error while associating an expense report to a Request |
|
| 503 Service Unavailable | circuitBreaker Circuit Breaker is open, please try again on a different node |
The server node might be unavailable, be retrying the request you may reach a healthy node |
| - | entityOffline Entity is offline, please try again later. |
|
| - | CLIQBOOK_APPROVAL_FAILURE |
This request cannot be approved due to trip approval failure. |
| - | CLIQBOOK_APPROVAL_RETRY |
This request cannot be approved immediately. Please try again later. |
| - | CLIQBOOK_CANCEL_FAILURE |
This request cannot be cancelled due to trip cancel failure. |
TRAVEL-RECEIPTS
Getting Started
Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.
The Travel Receipts service exposes receipt requests to inform E-Receipt partners which E-Receipts to send to SAP Concur and for which user. A partner can call the API and receive paged responses of receipt requests (a maximum of 25 receipt requests per page). When the next field is empty/null, the partner has reached the last page of receipt requests.
If the partner supplies a timestamp as a parameter, it is used as the start time for results. If not, the API retrieves the results from the last 24 hours.
Version
1.0
Regional Availability
US
https://us.api.concursolutions.com/travelreceipts/v1/receiptrequests
EMEA
https://emea.api.concursolutions.com/travelreceipts/v1/receiptrequests
Authentication
Partners must obtain an access token from the Authentication API.
The partner's access_token from the Authentication API response should then be used in the Authorization header of the Travel Receipts API calls.
Note: A token needs to be fetched for each datacenter, you cannot use the same token for US and EMEA.
Examples:
cURL:
curl -d "client_secret={YOUR SECRET}&client_id={YOUR CLIENT ID}&grant_type=client_credentials" https://us.api.concursolutions.com/oauth2/v0/token
HTTPie:
http -f POST https://us.api.concursolutions.com/oauth2/v0/token client_secret={YOUR SECRET} client_id={YOUR CLIENT ID} grant_type=client_credentials
Example Response
Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.
Below is a sample of receipt requests to show the response format a partner would receive from the API. The items are the receipt requests and the next links to the next page of results.
Receipt Request Response
Receipt Requests (Page 1)
Resp: {
"items": [
{
"requestId": "905be7a3-882e-4bdf-8184-206908142aed",
"vendor": "ZE",
"confirmationNumber": "324186883",
"firstName": "THOMAS",
"lastName": "METGER",
"segmentStartDate": "2018-01-30T14:40:00Z",
"segmentEndDate": "2018-02-01T21:55:00Z",
"requestDate": "2018-01-23T18:49:57.915931237Z"
},
{
"requestId": "89eaff84-1cbe-4a2f-9048-5884117bd17e",
"vendor": "ZE",
"confirmationNumber": "335512084",
"firstName": "CLYDE",
"lastName": "DUNCAN",
"segmentStartDate": "2018-01-23T15:30:00Z",
"segmentEndDate": "2018-01-27T18:00:00Z",
"requestDate": "2018-01-23T18:49:57.915933229Z"
},
{
"requestId": "df1b2194-97b7-4c97-9c8a-fe5e42a6326b",
"vendor": "ZE",
"confirmationNumber": "443502429",
"firstName": "SAM",
"lastName": "SELIMAN",
"segmentStartDate": "2018-03-16T18:15:00Z",
"segmentEndDate": "2018-03-20T01:00:00Z",
"requestDate": "2018-01-23T18:49:57.915935026Z"
},
{
"requestId": "b338497d-6443-4c19-ab1d-105bf6acf01c",
"vendor": "ZE",
"confirmationNumber": "4652321537",
"firstName": "WALTER",
"lastName": "RICHARD",
"segmentStartDate": "2018-01-22T14:00:00Z",
"segmentEndDate": "2018-01-25T17:00:00Z",
"requestDate": "2018-01-23T18:49:57.915936721Z"
},
{
"requestId": "29a8925f-56a1-4a37-b3dc-fab2d1f85a1d",
"vendor": "ZE",
"confirmationNumber": "212291436",
"firstName": "VAN",
"lastName": "CLYDE",
"segmentStartDate": "2018-01-22T16:00:00Z",
"segmentEndDate": "2018-01-25T23:00:00Z",
"requestDate": "2018-01-23T18:49:57.915938106Z"
},
{
"requestId": "8b803a73-8dd2-43bf-8f35-8aa6d24f82c1",
"vendor": "ZE",
"confirmationNumber": "934514835",
"firstName": "LYNN",
"lastName": "CAREY",
"segmentStartDate": "2018-01-23T18:45:00Z",
"segmentEndDate": "2018-01-26T03:00:00Z",
"requestDate": "2018-01-23T18:49:57.915939879Z"
},
{
"requestId": "36653406-08f5-425f-b186-653c53fcf3b1",
"vendor": "ZE",
"confirmationNumber": "244689456",
"firstName": "GEORGE",
"lastName": "STOLLEY",
"segmentStartDate": "2018-01-24T13:30:00Z",
"segmentEndDate": "2018-01-25T13:30:00Z",
"requestDate": "2018-01-23T18:49:57.915941244Z"
},
{
"requestId": "44c2267e-8630-4ea7-a958-a598d2000611",
"vendor": "ZE",
"confirmationNumber": "530203526",
"firstName": "CHRIS",
"lastName": "GALLAGHER",
"segmentStartDate": "2018-01-30T20:35:00Z",
"segmentEndDate": "2018-02-03T13:15:00Z",
"requestDate": "2018-01-23T18:49:57.915942604Z"
},
{
"requestId": "7d6bbb2f-2862-44aa-9764-c779fae94fe9",
"vendor": "ZE",
"confirmationNumber": "455319127",
"firstName": "STEVE",
"lastName": "LOCK",
"segmentStartDate": "2018-01-23T23:30:00Z",
"segmentEndDate": "2018-01-26T23:30:00Z",
"requestDate": "2018-01-23T18:49:57.915943946Z"
},
{
"requestId": "ade1df9d-629f-4a99-86a2-2c6cc87221fb",
"vendor": "ZE",
"confirmationNumber": "163724658",
"firstName": "TRACEY",
"lastName": "CAMPBELL",
"segmentStartDate": "2018-01-25T00:05:00Z",
"segmentEndDate": "2018-01-26T18:40:00Z",
"requestDate": "2018-01-23T18:49:57.915949116Z"
},
{
"requestId": "787bd2ba-aaaf-4e04-ae85-1f05a3679101",
"vendor": "ZE",
"confirmationNumber": "245527331",
"firstName": "SAMMY",
"lastName": "STEVENS",
"segmentStartDate": "2018-01-25T04:15:00Z",
"segmentEndDate": "2018-01-26T02:25:00Z",
"requestDate": "2018-01-23T18:49:57.915950543Z"
},
{
"requestId": "ee74ace2-67bf-4af5-b64e-6695f7ea971d",
"vendor": "ZE",
"confirmationNumber": "132759455",
"firstName": "DAVE",
"lastName": "SCHULTZ",
"segmentStartDate": "2018-02-03T02:07:00Z",
"segmentEndDate": "2018-02-08T16:50:00Z",
"requestDate": "2018-01-23T18:49:57.915951902Z"
},
{
"requestId": "9d783dfc-6bcd-4391-b659-53b673c7eb23",
"vendor": "ZE",
"confirmationNumber": "537355772",
"firstName": "GARY",
"lastName": "BOTTIS",
"segmentStartDate": "2018-01-23T02:25:00Z",
"segmentEndDate": "2018-01-26T16:35:00Z",
"requestDate": "2018-01-23T18:49:57.915953271Z"
},
{
"requestId": "6cb48fad-0468-4f6a-8e68-6bc2dfbdda5f",
"vendor": "ZE",
"confirmationNumber": "553257291",
"firstName": "NICOLE",
"lastName": "ELKIDGE",
"segmentStartDate": "2018-01-22T04:30:00Z",
"segmentEndDate": "2018-01-26T21:00:00Z",
"requestDate": "2018-01-23T18:49:57.915954617Z"
},
{
"requestId": "539039fc-11ad-46d9-83f8-45260391caa9",
"vendor": "ZE",
"confirmationNumber": "304450523",
"firstName": "NADIA",
"lastName": "KHAN",
"segmentStartDate": "2018-01-22T04:00:00Z",
"segmentEndDate": "2018-01-26T16:00:00Z",
"requestDate": "2018-01-23T18:49:57.915955955Z"
},
{
"requestId": "c5198cd7-e87e-4f07-86fa-a712dcd49bbf",
"vendor": "ZE",
"confirmationNumber": "248124345",
"firstName": "JAMIE",
"lastName": "COTTIGAN",
"segmentStartDate": "2018-01-29T23:00:00Z",
"segmentEndDate": "2018-01-31T21:00:00Z",
"requestDate": "2018-01-23T18:49:57.915957285Z"
},
{
"requestId": "d567bfed-b6ca-40c0-a1ae-f5c5339e9258",
"vendor": "ZE",
"confirmationNumber": "322723456",
"firstName": "SARAH",
"lastName": "STANLEY",
"segmentStartDate": "2018-06-06T19:14:00Z",
"segmentEndDate": "2018-06-09T16:40:00Z",
"requestDate": "2018-01-23T18:49:57.915958625Z"
},
{
"requestId": "f9ae54c7-eb19-494b-a46c-bb5d76f17973",
"vendor": "ZE",
"confirmationNumber": "312876745",
"firstName": "MELISSA",
"lastName": "NIAYE",
"segmentStartDate": "2018-01-26T22:50:00Z",
"segmentEndDate": "2018-02-09T20:45:00Z",
"requestDate": "2018-01-23T18:49:57.915961987Z"
},
{
"requestId": "6378174d-d38b-4f9a-af85-8c3033efc491",
"vendor": "ZE",
"confirmationNumber": "313324743",
"firstName": "SCOTTY",
"lastName": "THOMPSON",
"segmentStartDate": "2018-01-22T21:24:00Z",
"segmentEndDate": "2018-01-26T13:15:00Z",
"requestDate": "2018-01-23T18:49:57.915963318Z"
},
{
"requestId": "aab3ea49-a899-4ecf-90b0-ed474408447e",
"vendor": "ZE",
"confirmationNumber": "313853757",
"firstName": "MICHAEL",
"lastName": "CARSON",
"segmentStartDate": "2018-02-01T20:05:00Z",
"segmentEndDate": "2018-02-02T23:25:00Z",
"requestDate": "2018-01-23T18:49:57.915964654Z"
},
{
"requestId": "99268619-f42a-4abd-ae44-698a37791a4e",
"vendor": "ZE",
"confirmationNumber": "4332095991",
"firstName": "CECIL",
"lastName": "LEE",
"segmentStartDate": "2018-01-29T16:02:00Z",
"segmentEndDate": "2018-02-01T16:40:00Z",
"requestDate": "2018-01-23T18:49:57.915966004Z"
},
{
"requestId": "18b124b8-7fa3-438b-85c6-57e16e5b3258",
"vendor": "ZE",
"confirmationNumber": "346384323",
"firstName": "JOHN",
"lastName": "FRANK",
"segmentStartDate": "2018-04-25T16:00:00Z",
"segmentEndDate": "2018-04-29T23:30:00Z",
"requestDate": "2018-01-23T18:49:57.915967343Z"
},
{
"requestId": "f80ee9ba-2d04-416e-9a96-ac7b282b38a9",
"vendor": "ZE",
"confirmationNumber": "407480677",
"firstName": "STACEY",
"lastName": "SCOTT",
"segmentStartDate": "2018-02-05T18:00:00Z",
"segmentEndDate": "2018-02-09T10:30:00Z",
"requestDate": "2018-01-23T18:49:57.915968682Z"
},
{
"requestId": "bb8da2e0-c7c2-454b-84bf-c3a2f9ed37fb",
"vendor": "ZE",
"confirmationNumber": "553338341",
"firstName": "GEORGE",
"lastName": "TESSER",
"segmentStartDate": "2018-01-26T20:00:00Z",
"segmentEndDate": "2018-01-28T20:00:00Z",
"requestDate": "2018-01-23T18:49:57.9159701Z"
},
{
"requestId": "a2903477-f4a8-4159-bf9a-4f42cea47ce1",
"vendor": "ZE",
"confirmationNumber": "530244855",
"firstName": "ERICA",
"lastName": "VANASSEY",
"segmentStartDate": "2018-01-22T13:00:00Z",
"segmentEndDate": "2018-01-23T00:00:00Z",
"requestDate": "2018-01-23T18:49:57.915971485Z"
}
],
"next": "/v1/receiptrequests/1516561200/6443f257-03fe-5881-ac46-2e4865d944d3"
}
Receipt Requests (Page 2)
Resp: {
"items": [
{
"requestId": "9ecf0b1c-d000-422a-907a-fd8370e5ca54",
"vendor": "ZE",
"confirmationNumber": "531758043",
"firstName": "JENNIFER",
"lastName": "SALINGER",
"segmentStartDate": "2018-01-25T22:33:00Z",
"segmentEndDate": "2018-01-26T23:30:00Z",
"requestDate": "2018-01-23T18:49:58.194561445Z"
},
{
"requestId": "f455b342-a3cd-4b4c-83fa-7413d169c0ed",
"vendor": "ZE",
"confirmationNumber": "53158372",
"firstName": "CAROL",
"lastName": "CHAN",
"segmentStartDate": "2018-02-01T02:34:00Z",
"segmentEndDate": "2018-02-02T02:00:00Z",
"requestDate": "2018-01-23T18:49:58.194564178Z"
},
{
"requestId": "b05c5b1d-abd4-49f5-9d5b-844845fbe82f",
"vendor": "ZE",
"confirmationNumber": "320572345",
"firstName": "THOME",
"lastName": "MOORE",
"segmentStartDate": "2018-01-23T14:00:00Z",
"segmentEndDate": "2018-01-26T22:00:00Z",
"requestDate": "2018-01-23T18:49:58.194565985Z"
},
{
"requestId": "42e17778-2a4d-4846-8cad-a3905ce19bed",
"vendor": "ZE",
"confirmationNumber": "533244823",
"firstName": "KARIKA",
"lastName": "BHONDA",
"segmentStartDate": "2018-01-30T18:15:00Z",
"segmentEndDate": "2018-02-02T14:00:00Z",
"requestDate": "2018-01-23T18:49:58.194568541Z"
},
{
"requestId": "7f9ec889-8870-4b55-a38c-f4a70a5023d3",
"vendor": "ZE",
"confirmationNumber": "530066134",
"firstName": "BRUCE",
"lastName": "ALLEN",
"segmentStartDate": "2018-02-04T21:49:00Z",
"segmentEndDate": "2018-02-10T01:09:00Z",
"requestDate": "2018-01-23T18:49:58.19456995Z"
},
{
"requestId": "33f23e5a-cce8-4cb5-9d3c-38b1b739a7a1",
"vendor": "ZE",
"confirmationNumber": "553489629",
"firstName": "MICHAEL",
"lastName": "GEORGE",
"segmentStartDate": "2018-01-28T04:34:00Z",
"segmentEndDate": "2018-02-04T18:45:00Z",
"requestDate": "2018-01-23T18:49:58.194572246Z"
},
{
"requestId": "042c5743-a628-4a8a-9875-c56f07239fc7",
"vendor": "ZE",
"confirmationNumber": "570148920",
"firstName": "VINCENT",
"lastName": "LEE",
"segmentStartDate": "2018-01-21T23:00:00Z",
"segmentEndDate": "2018-01-25T17:55:00Z",
"requestDate": "2018-01-23T18:49:58.194573652Z"
},
{
"requestId": "553fd318-4cce-4249-bf78-2cf2654251a7",
"vendor": "ZE",
"confirmationNumber": "531491044",
"firstName": "STACY",
"lastName": "BRITLEY",
"segmentStartDate": "2018-02-05T04:16:00Z",
"segmentEndDate": "2018-02-09T23:25:00Z",
"requestDate": "2018-01-23T18:49:58.194575044Z"
},
{
"requestId": "492e4253-0e82-45f5-9cc6-0d67ae5557c7",
"vendor": "ZE",
"confirmationNumber": "323508328",
"firstName": "DAVID F",
"lastName": "SETTER",
"segmentStartDate": "2018-01-22T23:00:00Z",
"segmentEndDate": "2018-01-26T02:00:00Z",
"requestDate": "2018-01-23T18:49:58.194576479Z"
},
{
"requestId": "48ea6ec0-e9ab-45b0-847f-e2b0b67cb594",
"vendor": "ZE",
"confirmationNumber": "323311322",
"firstName": "KENT",
"lastName": "CLARKE",
"segmentStartDate": "2018-01-22T17:00:00Z",
"segmentEndDate": "2018-01-26T11:00:00Z",
"requestDate": "2018-01-23T18:49:58.194578761Z"
},
{
"requestId": "c56f954a-855a-4260-a6ff-21b14cca1f8f",
"vendor": "ZE",
"confirmationNumber": "530520555",
"firstName": "WILLIAM K",
"lastName": "MASS",
"segmentStartDate": "2018-02-22T14:00:00Z",
"segmentEndDate": "2018-02-25T23:00:00Z",
"requestDate": "2018-01-23T18:49:58.194580174Z"
},
{
"requestId": "162dcae7-ee6d-483e-bd04-af59008d437d",
"vendor": "ZE",
"confirmationNumber": "5332461523",
"firstName": "KUMAR",
"lastName": "QUASBY",
"segmentStartDate": "2018-01-30T20:03:00Z",
"segmentEndDate": "2018-02-09T14:00:00Z",
"requestDate": "2018-01-23T18:49:58.194581545Z"
},
{
"requestId": "b502e51a-ef74-4fdd-96d1-bac9ac35bccb",
"vendor": "ZE",
"confirmationNumber": "532550992",
"firstName": "JOSEPH",
"lastName": "STICK",
"segmentStartDate": "2018-03-30T03:45:00Z",
"segmentEndDate": "2018-04-01T20:30:00Z",
"requestDate": "2018-01-23T18:49:58.194582899Z"
},
{
"requestId": "624ffcfa-dc88-4fe0-b7bb-efdbecd9c5bb",
"vendor": "ZE",
"confirmationNumber": "483591442",
"firstName": "BETH ANN",
"lastName": "MCFADDEN",
"segmentStartDate": "2018-01-23T21:15:00Z",
"segmentEndDate": "2018-01-25T21:15:00Z",
"requestDate": "2018-01-23T18:49:58.194584223Z"
},
{
"requestId": "f3306920-9229-4402-86a8-15fbee176fcf",
"vendor": "ZE",
"confirmationNumber": "533179846",
"firstName": "KIMBERLY J",
"lastName": "YAMASAKI",
"segmentStartDate": "2018-01-21T22:00:00Z",
"segmentEndDate": "2018-01-25T20:00:00Z",
"requestDate": "2018-01-23T18:49:58.194585553Z"
},
{
"requestId": "668fb7a9-3c6f-4750-acc1-e45235c2cd98",
"vendor": "ZE",
"confirmationNumber": "416150344",
"firstName": "STEPHEN",
"lastName": "BUCK",
"segmentStartDate": "2018-01-22T18:00:00Z",
"segmentEndDate": "2018-02-26T18:00:00Z",
"requestDate": "2018-01-23T18:49:58.194586873Z"
},
{
"requestId": "d5f8f682-395c-4ac5-afd9-ddd33f331f38",
"vendor": "ZE",
"confirmationNumber": "3290203462",
"firstName": "SASHA",
"lastName": "MALONE",
"segmentStartDate": "2018-01-23T17:00:00Z",
"segmentEndDate": "2018-01-26T17:00:00Z",
"requestDate": "2018-01-23T18:49:58.194588192Z"
},
{
"requestId": "c92a58c1-1008-4b67-afa9-5db14ce37a7d",
"vendor": "ZE",
"confirmationNumber": "353272082",
"firstName": "ERIC",
"lastName": "ZELMET",
"segmentStartDate": "2018-01-22T04:00:00Z",
"segmentEndDate": "2018-01-23T04:00:00Z",
"requestDate": "2018-01-23T18:49:58.19459122Z"
},
{
"requestId": "5372a3ed-f0d0-423a-80a6-121c7c4b40d1",
"vendor": "ZE",
"confirmationNumber": "533211431",
"firstName": "YUNG",
"lastName": "LIU",
"segmentStartDate": "2018-03-07T18:12:00Z",
"segmentEndDate": "2018-03-11T05:09:00Z",
"requestDate": "2018-01-23T18:49:58.194592576Z"
},
{
"requestId": "a8659cc9-2cea-42b2-95a0-60ce9c3d3ff7",
"vendor": "ZE",
"confirmationNumber": "530001832",
"firstName": "SHANE",
"lastName": "VANDIGRAFF",
"segmentStartDate": "2018-01-29T18:23:00Z",
"segmentEndDate": "2018-02-02T21:00:00Z",
"requestDate": "2018-01-23T18:49:58.194593904Z"
},
{
"requestId": "5a30d47f-d0bd-491c-a624-5d8f6c7ec3fb",
"vendor": "ZE",
"confirmationNumber": "532808260",
"firstName": "SEAN F",
"lastName": "SMITH",
"segmentStartDate": "2018-01-22T17:00:00Z",
"segmentEndDate": "2018-01-29T17:00:00Z",
"requestDate": "2018-01-23T18:49:58.194595236Z"
},
{
"requestId": "b8704c41-abc5-4f12-9d6f-f0820741f558",
"vendor": "ZE",
"confirmationNumber": "532593796",
"firstName": "TROY P",
"lastName": "DENOIT",
"segmentStartDate": "2018-02-12T14:49:00Z",
"segmentEndDate": "2018-02-16T20:40:00Z",
"requestDate": "2018-01-23T18:49:58.194596581Z"
},
{
"requestId": "1d593afb-e486-4b15-9188-60f9e6228c62",
"vendor": "ZE",
"confirmationNumber": "531745217",
"firstName": "ROSS M",
"lastName": "CLYDE",
"segmentStartDate": "2018-02-05T13:45:00Z",
"segmentEndDate": "2018-02-07T22:40:00Z",
"requestDate": "2018-01-23T18:49:58.194597916Z"
},
{
"requestId": "42183276-8691-4ee2-b243-3a87f0035cfc",
"vendor": "ZE",
"confirmationNumber": "319920342",
"firstName": "KEVIN",
"lastName": "HERNANDEZ",
"segmentStartDate": "2018-01-22T03:02:00Z",
"segmentEndDate": "2018-01-26T00:00:00Z",
"requestDate": "2018-01-23T18:49:58.194599228Z"
},
{
"requestId": "fb05fe58-ebe7-4f32-a844-a6a468bbcff0",
"vendor": "ZE",
"confirmationNumber": "322384229",
"firstName": "WILLIAM",
"lastName": "BOYESE",
"segmentStartDate": "2018-01-22T15:45:00Z",
"segmentEndDate": "2018-01-22T18:30:00Z",
"requestDate": "2018-01-23T18:49:58.1946006Z"
}
],
"next": ""
}
Travel Receipts v1
Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.
The Travel Receipts service offers one endpoint for retrieving receipt requests.
The Travel Receipts service exposes receipt requests to inform e-receipt partners which e-receipts to send to SAP Concur and for which user.
If the partner supplies a timestamp, it is used as the start time for results. If not, the API retrieves the results from the last 24 hours.
Limitations: This API is not available in Implementation environments. This API is only available in the North American and EMEA Data Centers. This API is only available to SAP Concur e-receipt partners.
Products and Editions
- Concur Travel Professional Edition
- Concur Travel Standard Edition
Scope Usage
| Name | Description | Endpoint |
|---|---|---|
travel.receipts.read |
Retrieves a travel receipt. | GET |
Dependencies
None.
Access Token Usage
This API supports company level access tokens.
Retrieve Travel Receipt Requests
Retrieves all travel receipt requests for the partner.
The results of the API call are limited to a maximum of 25 receipt requests per page. The partner can navigate to the next page of results through the next field in the response. Each page keeps the same timestamp but will have a different key. The partner has reached the last page of results when next is null/empty.
Scopes
travel.receipts.read - Refer to Scope Usage for full details.
Request
URI
Template
https://{datacenterURI}/travelreceipts/v1/receiptrequests/{ts}/{key}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
ts |
integer |
int64 |
Timestamp to specify a start time (if blank, defaults to last 24 hours). |
key |
string |
uuid |
Current item key, populated from the previous response (from the next field in the response). |
Headers
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7235 Authorization
Payload
None.
Response
Status Codes
Headers
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7231 Content-Type
- RFC 7231 Date
- RFC 7231 Vary
- RFC 7231 Server
Payload
Example
{
"items":[
{
"requestId":"12e1234e-3fa2-11e9-b37e-6a1234b3ceb0",
"vendor":"ZE",
"confirmationNumber":"H1234567A1",
"firstName":"PAT",
"lastName":"DAVIS",
"segmentStartDate":"2019-03-14T00:30:00Z",
"segmentEndDate":"2019-03-14T18:00:00Z",
"requestDate":"2019-03-05T23:58:09.540514416Z"
},
{
"requestId":"34e1234e-3fa2-11e9-b37e-6a1234b3ceb0",
"vendor":"ZE",
"confirmationNumber":" H1234567A2",
"firstName":"MIKE",
"lastName":"PARKER",
"segmentStartDate":"2019-03-14T20:30:00Z",
"segmentEndDate":"2019-03-15T23:45:00Z",
"requestDate":"2019-03-05T23:58:09.540515177Z"
},
{
"requestId":"56e1234e-3fa2-11e9-b37e-6a1234b3ceb0",
"vendor":"ZE",
"confirmationNumber":" H1234567A3",
"firstName":"CHRIS",
"lastName":"MILLER",
"segmentStartDate":"2019-03-19T17:35:00Z",
"segmentEndDate":"2019-03-21T00:40:00Z",
"requestDate":"2019-03-05T23:58:09.540515833Z"
},
{
"requestId":"78e1234e-3fa2-11e9-b37e-6a1234b3ceb0",
"vendor":"ZE",
"confirmationNumber":" H1234567A4",
"firstName":"JANE",
"lastName":"DOE",
"segmentStartDate":"2019-03-06T05:53:00Z",
"segmentEndDate":"2019-03-07T21:45:00Z",
"requestDate":"2019-03-05T23:58:09.540520756Z"
}
],
"next":"/v1/receiptrequests/1551744000/12e1234e-3fa2-11e9-b37e-6a1234b3ceb0"
}
Schema
Response
| Name | Type | Format | Description |
|---|---|---|---|
items |
Array |
Receipt Request | An array of Receipt Request items. |
next |
string |
- | Key for the next page of results. |
Receipt Request
| Name | Type | Format | Description |
|---|---|---|---|
confirmationNumber |
string |
- | Confirmation number for the receipt request. |
firstName |
string |
- | First name of the guest for the receipt request. |
lastName |
string |
- | Last name of the guest for the receipt request. |
requestDate |
date-time |
ISO 8601 | Date of the receipt request. |
requestId |
uuid |
- | ID for the receipt request. |
segmentEndDate |
date-time |
ISO 8601 | End date for the receipt request segment. |
segmentStartDate |
date-time |
ISO 8601 | Start date for the receipt request segment. |
vendor |
string |
- | Vendor code for the receipt request. |
TRAVEL
Travel Services
Overview
The Travel services consists of a set of APIs that provide programmatic access to travel data such as itineraries, travel profiles, travel requests, and travel loyalty program information. These APIs are categorized into three sets of web services:
Itinerary
The Concur Itinerary web service can be used to pro grammatically access travel data such as trips and bookings in the Concur travel system. The Concur Travel system uses this data to match and consolidate bookings it receives from disparate sources and put these into consolidated travelers’ itineraries, providing travelers a convenient way to view their trips in a single itinerary view. Travelers can view their itineraries through mobile applications or other services.
Travel Profile Web Service
The Travel Profile Web Service consists of a set of resources that provide travel profile functionality customized in specific ways for developers, travel suppliers, and travel management companies (TMCs). Depending on who is using this web service, it provides the ability to update travel loyalty information, and subscribe and unsubscribe to travel profile changes.
Travel requests
Concur Travel Request web service is designed to help businesses control expenses by requiring employees to obtain approval before incurring expenses. It provides the ability to view requests and update the workflow for travel requests.
Trip approval
The Trip Approval resource allows clients to approve or reject trips. Clients send the unique identifier for the trip, the approver email and the workflow action to be performed (either approve or reject).
Itinerary Web Service (TMC/Third-Party)
The SAP Concur Itinerary Web Service allows Travel Management Companies (TMC), SAP Concur clients, and third-party developers to view and create travel related events in the Concur Travel system. TMCs can post bookings for any travel type. This web service can also be used by SAP Concur clients and third-party developers to request trip information for SAP Concur users. The public Itinerary XSD can be found here. In addition, the GetList XSD can be found here.
- GET List of Itineraries
- GET Itinerary Details
- POST Itinerary Details
- POST Itinerary Cancellation
- POST Booking Details
- POST Booking Cancellation
- Booking Object Elements
GET List of Itineraries
Retrieves trip summaries for the traveler specified in the OAuth token. This endpoint can also be used to get details for trips for a different user or the whole company. This is most often done when a Travel Management Company needs to get a list of trips on behalf of a user or company. During the request, a user with one of the following user roles from the user's company must authenticate through OAuth: Web Services Administrator for Professional, or Can Administer for Standard.
The response for this function can be divided into pages for easier processing.
Parameters
| Name | Description |
|---|---|
tripId |
The trip id |
startDate={_date_} |
The URL-encoded start date (in Coordinated Universal Time, aka UTC) for the trip. Format: YYYY-MM-DD. If no query parameters are provided, the start date is set to today's date - 30 days. The request will only return trips that are ongoing during the provided dates, either starting on the date, or starting before the date and ongoing during the provided date. |
endDate****={_date_} |
The URL-encoded UTC end date for the trip. Format: YYYY-MM-DD. If no query parameters are provided, the end date is set to today's date + 12 months. The request will only return trips that are ongoing during the provided dates, either ending on the date, or starting before the date and ongoing during the provided date. |
createdAfterDate****={_date_} |
The URL-encoded UTC date for when the trip was created. The query string will return trips created on or after this date. Used with the createdBeforeDate for finding trips created during a date range. Format: YYYY-MM-DD. |
createdBeforeDate****={_date_} |
The URL-encoded UTC date for when the trip was created. The query string will return trips created on or before this date. Used with the createdAfterDate for finding trips created during a date range. Format: YYYY-MM-DD. |
lastModifiedDate****={_date_} |
The last modified UTC date of the trips and any their associated bookings. This query string will return only the trips where the trip or any of its associated bookings have a last modified date that is greater or equal to the supplied time. The provided date/time can be anytime between now and the first date of trip creation in the database. The format is either the date or the date and time combined. |
bookingType={_type_} |
The trip includes at least one booking of this type. Format: Air, Car, Dining, Hotel, Parking, Rail, or Ride |
userid_type=login&userid_value=_{loginID}_ |
The loginID is the user's SAP Concur login ID. The userid_value of ALL can be sent to get trip summaries for all users at the company. The userid_type and userid_value parameters can only be used if the OAuth consumer has one of the user roles listed above. |
includeMetadata=true&ItemsPerPage={_number_}&Page={_number_} |
The includeMetadata query parameter combined with the ItemsPerPage and Page query parameters will cause the response to be divided into pages. The response will be wrapped in a ConcurResponse parent element, with both the response details and the paging metadata included. The details of the response are here. If the ItemsPerPage query parameter is not sent, the response will default to 200 if the Page query parameter is sent, or 1000 if the Page query parameter is not set. If the Page query parameter is not sent, the response will default to page 1. |
includeVirtualTrip=_1_ |
Virtual trips are segments booked offline through the Travel Request product. Set the includeVirtualTrip query parameter to 1 to include those trips in the list. |
includeCanceledTrips=_{true/false}_ |
The includeCanceledTrips query parameter will cause the request to also return trips with a status of Canceled. When this query parameter is set to true, the response will include the TripStatus element. |
Examples:
To get itinerary list for the entire company (OAuth consumer must have Admin user role):
https://www.concursolutions.com/api/travel/trip/v1.1/?startDate={startdate}&endDate={enddate}&_createdAfterDate={_date}&createdBeforeDate={date}&lastModifiedDate={date}&bookingType={type}&userid_type=login&userid_value=ALL
To get itinerary list for a single user (the OAuth consumer):
https://www.concursolutions.com/api/travel/trip/v1.1/?startDate={startdate}&endDate={enddate}&_createdAfterDate={_date}&createdBeforeDate={date}&lastModifiedDate={date}&bookingType={type}
To get itinerary list for a single user (other than the OAuth consumer):
https://www.concursolutions.com/api/travel/trip/v1.1/?startDate={startdate}&endDate={enddate}&_createdAfterDate={_date}&createdBeforeDate={date}&lastModifiedDate={date}&bookingType={type}&userid_type=login_id&userid_value={loginID}
XML Example Request by Start and End Date
GET /api/travel/trip/v1.1/?startDate=2012%2F02%2F01&endDate=2013%2F12%2F31 HTTP/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
...
XML Example Request by Booking Type and Start Date
GET /api/travel/trip/v1.1/?startDate=2012%2F02%2F01&bookingType=Air HTTP/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
...
XML Example Request by Created Date
GET /api/travel/trip/v1.1/?createdAfterDate=2012%2F02%2F01 HTTP/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
XML Example Request with Paging
GET /api/travel/trip/v1.1/?createdAfterDate=2012%2F02%2F01&includeMetadata=true&ItemsPerPage=2&Page=1 HTTP/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Get List of Itineraries Response
This request will return an ItineraryInfoList parent element with an ItineraryInfo child element for each trip summary for the specified traveler. Each ItineraryInfo element has the following child elements:
| Name | Description |
|---|---|
TripId |
Encrypted trip identifier value. |
TripName |
Name of the trip |
TripStatus |
The status of the trip. This element only appears if the includeCanceledTrips query parameter is used in the request. |
StartDateLocal |
The start date of the trip in the starting location's timezone. Format: YYYY-MM-DDThh:mm:ss. |
EndDateLocal |
The end date of the trip in the ending location's timezone. Format: YYYY-MM-DDThh:mm:ss. |
UserLoginId |
The user's login to SAP Concur. Only appears when the OAuth consumer has one of the specified admin roles. |
DateModifiedUtc |
The UTC date that this trip was last modified. Format: YYYY-MM-DDThh:mm:ss. |
id |
Trip ID URI with encrypted ID. |
Paging
If the includeMetadata and ItemsPerPage query parameters are included in the request, the response will include a ConnectResponse parent element with the following elements:
| Name | Description |
|---|---|
Data |
This parent element contains the response as detailed above. |
Metadata |
This parent element contains the Paging elements. |
Paging Elements
The parent element of the paging information. Contains the following child elements:
| Name | Description |
|---|---|
TotalPages |
The total number of pages the query returned. |
TotalItems |
The total number of itineraries the query returned. |
CurrentPage |
The page number for the set of results in the current response. |
ItemsPerPage |
The number of items set to display per page. |
PreviousPageURL |
The URI to the previous page of results. This element will be empty when there are no previous pages. |
NextPageURL |
The URI to the next set of results. This element will be empty when there are no next pages. |
XML Example of Successful Response
HTTP/1.1 200 OK
Content-Type: application/xml
...
<?xml version="1.0" encoding="utf-8"?>
<ItineraryInfoList xmlns="http://www.concursolutions.com/api/travel/trip/2010/06" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<ItineraryInfo>
<TripId>naIzQJ0y2DBWjCIQOb2SHTsozwBsHDkdP</TripId>
<TripName>Trip from Baltimore to New York</TripName>
<StartDateLocal>2012-02-15T09:00:00</StartDateLocal>
<EndDateLocal>2012-02-21T17:30:00</EndDateLocal>
<UserLoginId>cm@example.com</UserLoginId>
<DateModifiedUtc>2012-02-14T17:13:07</DateModifiedUtc>
<id>https://www.concursolutions.com/api/travel/trip/v1.1/naIzQJ0y2DBWjCIQOb2SHTsozwBsHDkdP</id>
</ItineraryInfo>
<ItineraryInfo>
<TripId>I2uwiJJw8r7Owl3IWlSie9WIelxhAhwiL</TripId>
<TripName>Trip from Baltimore to Seattle</TripName>
<StartDateLocal>2012-03-26T09:00:00</StartDateLocal>
<EndDateLocal>2012-03-29T17:30:00</EndDateLocal>
<DateModifiedUtc>2012-03-24T19:00:00</DateModifiedUtc>
<UserLoginId>cm@example.com</UserLoginId>
<id>https://www.concursolutions.com/api/travel/trip/v1.1/I2uwiJJw8r7Owl3IWlSie9WIelxhAhwiL</id>
</ItineraryInfo>
</ItineraryInfoList>
XML Example of Successful Response with Paging
HTTP/1.1 200 OK
Content-Type: application/xml
...
<ConnectResponse>
<Metadata>
<Paging>
<TotalPages>38</TotalPages>
<TotalItems>187</TotalItems>
<CurrentPage>2</CurrentPage>
<ItemsPerPage>2</ItemsPerPage>
<PreviousPageURL>https://www.concursolutions.com/api/travel/trip/v1.1/?createdAfterDate=2012%2F02%2F01&itemsPerPage=5&page=3&includeMetaData=true</PreviousPageURL>
<NextPageURL>https://www.concursolutions.com/api/travel/trip/v1.1/?createdAfterDate=2012%2F02%2F01&itemsPerPage=5&page=1&includeMetaData=true</NextPageURL>
</Paging>
</Metadata>
<Data>
<ItineraryInfoList xmlns="http://www.concursolutions.com/api/travel/trip/2010/06" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<ItineraryInfo>
<TripId>naIzQJ0y2DBWjCIQOb2SHTsozwBsHDkdP</TripId>
<TripName>Trip from Baltimore to New York</TripName>
<StartDateLocal>2012-02-15T09:00:00</StartDateLocal>
<EndDateLocal>2012-02-21T17:30:00</EndDateLocal>
<UserLoginId>cm@example.com</UserLoginId>
<DateModifiedUtc>2012-02-14T17:13:07</DateModifiedUtc>
<id>https://www.concursolutions.com/api/travel/trip/v1.1/naIzQJ0y2DBWjCIQOb2SHTsozwBsHDkdP</id>
</ItineraryInfo>
<ItineraryInfo>
<TripId>I2uwiJJw8r7Owl3IWlSie9WIelxhAhwiL</TripId>
<TripName>Trip from Baltimore to Seattle</TripName>
<StartDateLocal>2012-03-26T09:00:00</StartDateLocal>
<EndDateLocal>2012-03-29T17:30:00</EndDateLocal>
<DateModifiedUtc>2012-03-24T19:00:00</DateModifiedUtc>
<UserLoginId>cm@example.com</UserLoginId>
<id>https://www.concursolutions.com/api/travel/trip/v1.1/I2uwiJJw8r7Owl3IWlSie9WIelxhAhwiL</id>
</ItineraryInfo>
</ItineraryInfoList>
</Data>
</ConnectResponse>
GET Itinerary Details
Retrieves the details for the specified trip. By default, the OAuth consumer should be the owner of the trip. This endpoint can also be used to get details for trips that the OAuth consumer does not own. This is most often done when a Travel Management Company needs to get trip details on behalf of a user. The TMC must be registered with SAP Concur and have a SAP Concur account that has one of the following user roles: Web Services Administrator for Professional, or Can Administer for Standard.
The returned elements will vary based on the following conditions:
- Some elements, such as AirlineTickets or RailPayments, will only appear for bookings of the appropriate type.
- Amount values, such as Rate or Tax, will only appear if the requestor is the source of the booking. All other suppliers will not receive the amount elements associated with the bookings.
- Some elements, such as SabreDKNumber, will only appear if the booking was created by the relevant GDS.
- Some elements are vendor-specific and will only appear in responses for the associated vendor.
This documentation contains the full set of possible elements that can be returned. No itinerary can contain all of the possible elements, so the response will always be a subset of the possible returned values.
Parameters
| Name | Description |
|---|---|
{_tripId_} |
Required. The identifier for the desired trip. |
userid_type=login&userid_value=_{loginID}_ |
The loginID is the user's SAP Concur login ID. The userid_value of ALL can be sent to get trip summaries for all users at the company. The userid_type and userid_value parameters can only be used if the OAuth consumer has one of the user roles listed above. |
systemFormat=_{format}_ |
The systemFormat query parameter can be used to specify that the response is formatted for a different system. The supported value is Tripit. |
Get Itinerary Details Response
This request will return an Itinerary parent element with a subset of the following child elements:
Parameters
| Name | Description |
|---|---|
BookedByFirstName |
The first name of the person who booked the trip. |
BookedByLastName |
The last name of the person who booked the trip. |
BookedVia |
The booking method for the trip. |
CancelComments |
The comments provided if the itinerary is cancelled. Maximum length: 256 characters. |
Comments |
Optional comments. Maximum length: 512 characters. |
DateBookedLocal |
The date the trip was booked, in the local time of the booking location. Format: YYYY-MM-DDThh:mm:ss |
DateCreatedUtc |
The date that this trip was created, in UTC. Format: YYYY-MM-DDThh:mm:ss |
DateModifiedUtc |
The date that this trip was last modified, in UTC. Format: YYYY-MM-DDThh:mm:ss |
Description |
The trip description. Maximum length: 512 characters. |
EndDateLocal |
The end date of the trip in the ending location's timezone. Format: YYYY-MM-DDThh:mm:ss |
EndDateUtc |
The end date of the trip, in UTC. Format: YYYY-MM-DDThh:mm:ss |
IsPersonal |
Whether the trip is a Business or Leisure trip. Format: true/false. |
ProjectName |
The associated project name for the trip. Maximum length: 255 characters. |
StartDateLocal |
The start date of the trip in the starting location's timezone. Format: YYYY-MM-DDThh:mm:ss |
StartDateUtc |
The start date of the trip, in UTC. Format: YYYY-MM-DDThh:mm:ss |
TripName |
Name of the trip. Maximum length: 255 characters. |
Bookings |
This parent element will contain a Booking child element for each booking associated with this itinerary. Refer to the Booking Child Elements table. |
RuleViolations |
The list of rule violations associated with the itinerary. This parent element contains a RuleViolation child element for each associated rule violation. Refer to the Public Itinerary XSD for more information. |
Status |
The status of the itinerary. One of the following: 0 = Confirmed; 1 = Ticketed by agent; 2 = Canceled |
Booking Child Elements
| Name | Description |
|---|---|
BookingSource |
The name of the booking source for this booking. A booking source is a textual name the system uses to track where a booking took place. |
DateBookedLocal |
The date the booking was created, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss |
DateCreatedUtc |
The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss |
DateModifiedUtc |
The date the booking was last modified, in UTC. Format: YYYY-MM-DDThh:mm:ss |
FormOfPaymentName |
The name of the form of payment for the booking. |
FormOfPaymentType |
The type of the form of payment. |
PassengerCount |
The number of passengers included in the booking. |
RecordLocator |
Record locator for this booking. This is often six alphanumeric characters but can have other formats depending on the booking source. |
RetrievedDateUtc |
The date the booking was last accessed, in UTC. Format: YYYY-MM-DDThh:mm:ss |
TicketMailingAddress |
The mailing address for the booked ticket, if any. |
TicketPickupLocation |
The pickup location for the booked ticket, if any. |
TicketPickupNumber |
The confirmation number to pick up the booked ticket, if any. |
AirfareQuotes |
List of stored airfare quotes. This parent element has a Quote child element for each airfare quote. The Quote parent element contains Airfare Quotes Child Elements |
AirlineTickets |
List of Airline Tickets. This parent element contains Airline Tickets Child Elements |
Charges |
The charges for the booking. |
MiscChargeOrders |
This parent element has a MiscellaneousChargeOrder child element for each included miscellaneous charge. The MiscellaneousChargeOrder parent element contains Miscellaneous Charge Order Child Elements |
Passengers |
This parent element has a Passenger child element for each included passenger. Refer to the Passenger Child Elements |
PassPrograms |
This parent element has Pass Program child elements for each pass program associated with the booking. |
PhoneNumbers |
This parent element has Phone Number Data child elements for each phone number associated with the booking. |
RailPayments |
This parent element has Rail Payment Child Elements |
Segments |
This parent element will contain at least one of the following child elements: Air, Car, Hotel, Dining, Ride, Rail, Parking. |
Delivery |
The method used to deliver this booking. Refer to the Delivery Method Child Elements |
WaitListSegments |
Information will appear in this element if the segment is on a waiting list. |
Warnings |
The warnings associated with the booking. |
WebAddresses |
List of web addresses. This parent element includes Web Address Data child elements for each associated web address. |
BookingReferrer |
BookingReferrer is used only in specific source tracking scenarios when there is a need to distinguish between bookings with the same BookingSources coming through different flows. Do not populate without coordinating with your technical contact. The supported values are: Concur Travel, Sign-in with SAP Concur, Supplier Mobile, Supplier Web. |
Airfare Quotes Child Elements
| Name | Description |
|---|---|
BaseFare |
The base fare of the booking quote. |
BaseFareCurrency |
The 3-letter ISO 4217 currency code for the booking quote. |
BaseFareNuc |
The base fare in NUC. |
BaseFareNucCurrency |
The 3-letter ISO 4217 currency code for the base fare in NUC. |
DateCreatedUtc |
The date the quote was created, in UTC. Format: YYYY-MM-DDThh:mm:ss |
DateModifiedUtc |
The date the quote was last modified, in UTC. Format: YYYY-MM-DDThh:mm:ss |
Endorsements |
Notes from the airline if it endorses the ticket as acceptable on a different airline. |
IssueByDate |
The date the quote must be issued by. Format: YYYY-MM-DDThh:mm:ss |
TotalFare |
The total price of the booking. |
TotalFareCurrency |
The 3-letter ISO 4217 currency code for the total fare. |
AirlineCharges |
The charges applied by the airline. This parent element contains a Fixed child element for each fixed charge from the airline. |
Taxes |
The taxed applied to this airline ticket. |
Airline Tickets Child Elements
| Name | Description |
|---|---|
ManualAirlineTicket |
The manual airline ticket for the booking. |
AirlineTicket |
The airline ticket for the booking. |
AirlineAdjustment |
Any adjustment made to the booking. |
Miscellaneous Charge Order Child Elements
| Name | Description |
|---|---|
DateCreatedUtc |
The date the charge order was created, in UTC. Format: YYYY-MM-DDThh:mm:ss |
DateModifiedUtc |
The date the charge order was last modified, in UTC. Format: YYYY-MM-DDThh:mm:ss |
IssueDate |
The date the charge order was issued. Format: YYYY-MM-DDThh:mm:ss |
PlatingCarrierNumericCode |
Part of the ticket number that indicates the airline code. This is a three digit number. For example: 001=American, 005=Continental, 006=Delta, 012=Northwest |
PlatingControlNumber |
Part of the ticket number that indicates the ticket control number. Format: Ten digit number. |
TotalAmount |
The total amount of charge orders for the ticket. |
TotalAmountCurrency |
The 3-letter ISO 4217 currency code for the total charge order amount. |
Pass Programs Child Elements
| Name | Description |
|---|---|
Amount |
The program amount. |
Name |
The program name. |
Type |
The program type. |
UserFirstName |
The first name of the passenger. |
UserLastName |
The last name of the passenger. |
Phone Number Data Child Elements
| Name | Description |
|---|---|
PassengerRPH |
Indicates the passenger to whom this phone number belongs. |
PhoneNumber |
The passenger's phone number. |
Type |
The type of phone number. |
Description |
The description for the phone number. |
Rail Payments Child Elements
| Name | Description |
|---|---|
RailPayment |
The payment information for a rail booking. |
RailAdjustment |
The amount adjusted for a rail booking. Refer to the Public Itinerary XSD for more information. |
Delivery Method Child Elements
| Name | Description |
|---|---|
LocationAdditionalDetails |
Additional information about the delivery location. |
AddressLine1 |
The delivery address. |
AddressLine2 |
The delivery address. |
City |
The delivery address. |
Country |
The delivery address. |
LocationDesc |
Description of the delivery location. |
Email |
The delivery email contact. |
Latitude |
The delivery address. |
Longitude |
The delivery address. |
LocationName |
The name of the delivery location. |
PhoneNumber |
The phone number of the delivery contact. |
ReferenceNumber |
The reference number for the delivery. |
State |
The delivery address. |
Type |
The type of delivery address. |
Zip |
The delivery address. |
Web Address Data Child Elements
| Name | Description |
|---|---|
PassengerRPH |
Indicates the passenger to whom this web address belongs. |
WebAddress |
Web address. Format: email address or URL. Maximum length: 250 characters. |
Format |
Format of the web address. Format: E=Email, U=URL, I=IM |
Type |
Type code for web address. Format: TKT, RES, BUS |
Description |
Free text describing the web address. Maximum length: 50 characters. |
Passenger Child Elements
| Name | Description |
|---|---|
FirstNameNumber |
The number of characters in the passenger's first name. |
LastNameNumber |
The number of characters in the passenger's last name. |
NameFirst |
The passenger's first name. |
NameLast |
The passenger's last name. |
NameMiddle |
The passenger's middle name. |
NamePrefix |
The passenger's name prefix. |
NameRemark |
Additional details about the passenger's name. |
NameSuffix |
The passenger's name suffix. |
NameTitle |
The passenger's name title. |
TextName |
The user's full name. |
FrequentTravelerProgram |
The passenger's loyalty program identifier. This parent element contains the FrequentFlyer and RailProgram child elements. |
FrequentFlyer |
The passenger's frequent flyer program details. This parent element has Frequent Flyer Child Elements |
RailProgram |
The passenger's rail loyalty program details. This parent element has Rail Program Child Elements |
Frequent Flyer Child Elements
| Name | Description |
|---|---|
AirlineVendor |
The vendor of the frequent flyer program. |
Description |
The program description. |
DiscountProgramExpirationDate |
The date the discount program enrollment expires. Format: YYYY-MM-DDThh:mm:ss |
DiscountProgramType |
The type of discount program. |
FrequentFlyerNumber |
The passenger's identifier for the program. |
ProgramVendor |
The program vendor. |
Status |
The passenger's program status. |
StatusExpirationDate |
The expiration date for the passenger's program status. |
Rail Program Child Elements
| Name | Description |
|---|---|
Description |
Description of the discount program. |
DiscountProgramExpirationDate |
The date the discount program enrollment expires. Format: YYYY-MM-DDThh:mm:ss |
DiscountProgramType |
The type of discount program. |
ProgramNumber |
The passenger's identifier for the program. |
ProgramVendor |
The program vendor. |
Status |
The passenger's program status. |
StatusExpirationDate |
The expiration date for the passenger's program status. |
XML Example of Successful Response
HTTP/1.1 200 OK
Content-Type: application/xml
...
<?xml version="1.0" encoding="utf-8"?>
<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
<id>https://www.concursolutions.com/api/travel/trip/v1.1/CNQR1234567890</id>
<ItinLocator>CNQR1234567890</ItinLocator>
<ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
<ItinSourceName>ConcurTravel</ItinSourceName>
<TripName>Trip from Dallas to Seattle</TripName>
<Comments />
<StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<BookedVia>EveryGDS</BookedVia>
<BookedByFirstName>Chris</BookedByFirstName>
<BookedByLastName>Miller</BookedByLastName>
<DateBookedLocal>2012-07-24T19:15:52</DateBookedLocal>
<Bookings>
<Booking>
<Segments>
<Car>
<Vendor>CQ</Vendor>
<Status>HK</Status>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
<ConfirmationNumber>F1672664579</ConfirmationNumber>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<StartCityCode>SEA</StartCityCode>
<EndCityCode>SEA</EndCityCode>
<StartLocation>SEA</StartLocation>
<EndLocation>SEA</EndLocation>
<Class>E</Class>
<Body>C</Body>
<Transmission>M</Transmission>
<AirCondition>R</AirCondition>
<NumCars>1</NumCars>
<DiscountCode>346660</DiscountCode>
<DailyRate>44.0000</DailyRate>
<TotalRate>44.0000</TotalRate>
<RateType>D</RateType>
<Currency>USD</Currency>
<Charges>
<Fixed>
<Description>Dropoff Fee</Description>
<Currency>USD</Currency>
<Amount>0.0000</Amount>
<IsPrimary>false</IsPrimary>
<SemanticsCode>DROPOFFFEE</SemanticsCode>
<SemanticsVendorType>C</SemanticsVendorType>
</Fixed>
<RateWithAllowance>
<Currency>USD</Currency>
<Amount>44.0000</Amount>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<IsPrimary>true</IsPrimary>
<SemanticsCode>DAYS</SemanticsCode>
<SemanticsVendorType>C</SemanticsVendorType>
<PerUnit>DAY</PerUnit>
<NumUnits>1.0000</NumUnits>
<AllowanceNumUnits>250.0000</AllowanceNumUnits>
<AllowanceAmount>0.2400</AllowanceAmount>
<AllowanceIsUnlimited>false</AllowanceIsUnlimited>
</RateWithAllowance>
</Charges>
</Car>
</Segments>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>C123456789</RecordLocator>
<BookingSource>ConcurCars</BookingSource>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<ItinSourceName>TravelSupplier</ItinSourceName>
<PassengerCount>1</PassengerCount>
</Booking>
<Booking>
<Segments>
<Hotel>
<Vendor>CQ</Vendor>
<Status>GK</Status>
<StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<ConfirmationNumber>3364214265</ConfirmationNumber>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<RateCode>LV4</RateCode>
<Name>CONCUR HOTEL</Name>
<HotelPropertyId>CONQ</HotelPropertyId>
<CheckinTime>00:00</CheckinTime>
<CheckoutTime>00:00</CheckoutTime>
<NumPersons>1</NumPersons>
<NumRooms>1</NumRooms>
<CancellationPolicy>Cxl 1 day prior to Arrival</CancellationPolicy>
<DailyRate>240.3500</DailyRate>
<Currency>USD</Currency>
<RoomDescription>1 KING BED ACCESSIBLE ROOM - K1RRC</RoomDescription>
<Charges>
<Rate>
<Currency>USD</Currency>
<Amount>240.3500</Amount>
<StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
<IsPrimary>false</IsPrimary>
<SemanticsCode>ROOMRATE</SemanticsCode>
<SemanticsVendorType>H</SemanticsVendorType>
<PerUnit>DAY</PerUnit>
<NumUnits>3.0000</NumUnits>
</Rate>
</Charges>
</Hotel>
</Segments>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>0987654321</RecordLocator>
<BookingSource>ConcurHotel</BookingSource>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<OriginalItinLocator>33491211</OriginalItinLocator>
<ItinSourceName>ConcurTravel</ItinSourceName>
<PassengerCount>1</PassengerCount>
</Booking>
</Bookings>
</Itinerary>
XML Response in TripIt Format
<?xml version="1.0" encoding="utf-8"?>
<Response>
<Trip>
<id>73014481752</id>
<relative_url>/api/travel/trip/v1.1/73014481752</relative_url>
<start_date>2013-08-21</start_date>
<end_date>2013-08-24</end_date>
<display_name>Strategy Team meeting</display_name>
<is_private>true</is_private>
</Trip>
<AirObject>
<booking_site_conf_num>RL10001005</booking_site_conf_num>
<booking_site_name>Concur Travel</booking_site_name>
<booking_site_phone></booking_site_phone>
<booking_site_url>https://www.concursolutions.com</booking_site_url>
<record_locator>4294993825</record_locator>
<supplier_conf_num>CN10001005</supplier_conf_num>
<supplier_contact></supplier_contact>
<supplier_email_address></supplier_email_address>
<supplier_name></supplier_name>
<supplier_phone></supplier_phone>
<supplier_url></supplier_url>
<is_purchased>1</is_purchased>
<notes></notes>
<restrictions></restrictions>
<total_cost></total_cost>
<Segment>
<StartDateTime>
<date>2013-08-21</date>
<time>07:45:00</time>
</StartDateTime>
<EndDateTime>
<date>2013-08-21</date>
<time>13:03:00</time>
</EndDateTime>
<start_airport_code>PHX</start_airport_code>
<start_gate>A11</start_gate>
<start_terminal>4</start_terminal>
<end_airport_code>ORD</end_airport_code>
<end_gate>F8</end_gate>
<end_terminal>2</end_terminal>
<marketing_airline>US</marketing_airline>
<marketing_flight_number>1</marketing_flight_number>
<aircraft>320</aircraft>
<duration></duration>
<distance>1433</distance>
<notes></notes>
<seats></seats>
<service_class>Economy</service_class>
<stops>Nonstop</stops>
</Segment>
<Segment>
<StartDateTime>
<date>2013-08-24</date>
<time>13:55:00</time>
</StartDateTime>
<EndDateTime>
<date>2013-08-24</date>
<time>16:58:00</time>
</EndDateTime>
<start_airport_code>ORD</start_airport_code>
<start_gate></start_gate>
<start_terminal></start_terminal>
<end_airport_code>PHX</end_airport_code>
<end_gate></end_gate>
<end_terminal></end_terminal>
<marketing_airline>US</marketing_airline>
<marketing_flight_number>1728</marketing_flight_number>
<aircraft>A320</aircraft>
<duration></duration>
<distance></distance>
<notes></notes>
<seats></seats>
<service_class>Economy</service_class>
<stops> stops</stops>
</Segment>
<Traveler>
<first_name>William</first_name>
<middle_name></middle_name>
<last_name>Never</last_name>
<frequent_traveler_num></frequent_traveler_num>
<frequent_traveler_supplier></frequent_traveler_supplier>
<ticket_num></ticket_num>
</Traveler>
</AirObject>
</Response>
POST Itinerary Details
Description
Creates a new trip or updates an existing trip. A new trip will be created if the trip dates span no existing trip and the request doesn't include a tripId. If a tripId is included in the URI it will update the specified trip. The full trip information is included in the update request, which replaces the existing trip.
This endpoint can be used to create trips for a user that is not the OAuth consumer. This is most often done when a travel supplier or Travel Management Company needs to create a trip on behalf of a user. The supplier or TMC must be registered with SAP Concur and have an SAP Concur account that has one of the following user roles: Web Services Administrator for Professional, or Can Administer for Standard.
Agency Proposals
Travel Management Companies for SAP Concur clients with the Agency Proposal feature of Travel Request can send proposed itineraries using the Itinerary web service. The TMC will indicate that the itinerary is a proposal using the TripStatus element. The request must also include the CustomAttributes element and its child elements.
| Query Parameters - Required | Supported Content Types |
|---|---|
| None | application/xml |
Query Parameters - Optional
- {tripId}
The identifier for the desired trip. Provided if the request is updating an existing trip. - userid_type=login_id&userid_value={loginID}
The SAP Concur loginID of the user that owns the trip. Can be used when creating a new trip or updating an existing trip. The userid_type and userid_value parameters can only be used if the OAuth consumer has the user role listed above.
Examples:
To post a new trip for the OAuth consumer:
https://www.concursolutions.com/api/travel/trip/v1.1
To update a trip for the OAuth consumer:
https://www.concursolutions.com/api/travel/trip/v1.1?tripId={_tripId_}
To post a trip for a user other than the OAuth consumer:
https://www.concursolutions.com/api/travel/trip/v1.1?userid_type=login_id&userid_value={_loginID_}
| Request Headers - Required | Request Headers - Optional |
|---|---|
| Authorization header with OAuth token for valid SAP Concur user. To post trips for users other than the OAuth consumer, the OAuth consumer must have one of the following user roles in SAP Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard. | None |
Content Body
This function requires as its arguments an Itinerary parent element. The parent element contains the following child elements:
Required Elements
| Element | Description |
|---|---|
| TripName | Name of the trip. Maximum length: 255 characters. |
| TripStatus | The status of the itinerary. One of the following: 0 - Confirmed 1 - Ticketed 2 - Canceled 6 - Proposal 7 - Booked Proposal |
Required Elements for Agency Proposal
| Element | Description |
|---|---|
| ClientLocator | The unique identifier for the batch of proposals. All proposals in the batch should have the same value. |
| TravelRequestId | The identifier for the travel request that the proposal is associated with. |
| CustomAttributes | This parent element will contain CustomAttributes child element. The CustomAttributes child elements are detailed in the CustomAttributes Elements table. |
CustomAttributes Elements - Required
| DataType | Name | Data Supported Values | Comment |
|---|---|---|---|
| Numeric | ProposalBatchSize | 1 to 3 | The number of proposals in the batch. Maximum: 3 |
| Numeric | ProposalSequenceIndex | 1 to 3 | The index of the proposal in the batch of proposals. |
| Text | AutoSelectProposal | True, False | If true, then the proposal will be selected accordingly and replace the segments previously entered by the user. If False, then the proposal will be up to the user to decide which proposal s/he wants to manually select. |
| Text | TicketIssued | True, False | Are the tickets for this proposal issued or not. |
| Text | DisplayOnItinerary | True | The value for this element has to be 'True'. |
| N/A | DisplayTitle | N/A | This element should be empty. |
| N/A | ExternalId | N/A | This element should be empty. |
Optional Elements
| Element | Description |
|---|---|
| BookedByFirstName | First name of the trip owner. |
| BookedByLastName | Last name of the trip owner. |
| Bookings | This parent element will contain a Booking child element for each booking associated with this itinerary. The Booking child elements are detailed in the Booking Elements table. |
| CancelComments | User supplied comments if the trip is cancelled. 256 Characters Maximum |
| Comments | Comments on the itinerary. 512 Characters Maximum |
| DateBookedLocal | The date the trip was booked, in the local time of the booking location. Format: YYYY-MM-DDThh:mm:ss |
| Description | The trip description. Maximum length: 512 characters. |
| IsPersonal | Whether the trip is a Business or Leisure trip. |
| ProjectName | The associated project name for the trip. Maximum length: 255 characters. |
| RuleViolations | The list of rule violations associated with the itinerary. This parent element contains a |
Booking Elements - Required
| Element | Description |
|---|---|
| BookingSource | The name of the booking source for this booking. A booking source is a textual name the system uses to track where a booking took place. This could be a GDS, OTA, Vendor code for Supplier website, or Supplier Direct Connect API. |
| RecordLocator | The unique identifier for the booking. Send the value for an existing booking to update an existing trip. |
Booking Elements - Optional
| Element | Description |
|---|---|
| BookingOwner | Indicates the tool that supplied the booking to Concur Travel. |
| Source | Obsolete, supported for backward compatibility. |
| DateBookedLocal | The date the booking was created, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss |
| FormOfPaymentName | The name of the form of payment for the booking. |
| FormOfPaymentType | The type of the form of payment. |
| TicketMailingAddress | The mailing address for the booked ticket, if available. |
| TicketPickupLocation | The pickup location for the booked ticket, if available. |
| TicketPickupNumber | The confirmation number for the booked ticket, if available. |
| AirfareQuotes | List of stored airfare quotes for this booking. |
| Airline Tickets | List of airline tickets for this booking. |
| Charges | List of charges for this booking. |
| MiscChargeOrders | List of Miscellaneous AirCharges for this booking. |
| Passengers | This parent element contains a Passenger child element for each booked passenger. The Passenger child element contains the following child elements: NameFirst - The first name of the passenger. NameLast (optional) - The last name of the passenger. NameMiddle - The middle name of the passenger. NamePrefix - The passenger's name prefix. NameRemark - Additional details about the passenger's name. NameSuffix - The passenger's name suffix. NameTitle - The passenger's name title. TextName - The user's full name as entered in the booking tool if different from the name in the database. FrequentTravelerProgram - Passenger's loyalty programs. |
| PassPrograms | List of Pass Programs for this booking. |
| PhoneNumbers | List of Phone numbers associated with this booking. |
| RailPayments | List of Rail payments associated with rail segments in this booking. |
| Segments | This parent element will contain at least one of the following child elements: Air, Car, Hotel, Dining, Ride, Rail, Parking, Event. |
| Delivery | The method this booking was delivered. |
| WaitListSegments | The segments that the traveler is waitlisted for this booking. |
| Warning | The warnings associated with the booking. |
| WebAddresses | List of web addresses such as emails, pickup URLs, etc. associated with this booking. |
| BookingReferrer | BookingReferrer is used only in specific source tracking scenarios when there is a need to distinguish between bookings with the same BookingSources coming through different flows. Do not populate without coordinating with your technical contact. The supported values are: Concur Travel, Sign-in with SAP Concur, Supplier Mobile, Supplier Web |
XML Example Request
POST /api/travel/trip/v1.1?userid_type=login_id&userid_value=cm@example.com HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Content-Type: application/xml
...
<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
<ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
<ItinSourceName>ConcurConnectAPI</ItinSourceName>
<TripName>Trip from Dallas to Seattle</TripName>
<Comments />
<StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<BookedByFirstName>Chris</BookedByFirstName>
<BookedByLastName>Miller</BookedByLastName>
<Bookings>
<Booking>
<Segments>
<Car>
<Vendor>CQ</Vendor>
<Status>HK</Status>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
<ConfirmationNumber>F1672664579</ConfirmationNumber>
<StartCityCode>SEA</StartCityCode>
<EndCityCode>SEA</EndCityCode>
<StartLocation>SEA</StartLocation>
<EndLocation>SEA</EndLocation>
<Class>E</Class>
<Body>C</Body>
<Transmission>M</Transmission>
<AirCondition>R</AirCondition>
<NumCars>1</NumCars>
<DiscountCode>346660</DiscountCode>
<DailyRate>44.0000</DailyRate>
<TotalRate>44.0000</TotalRate>
<RateType>D</RateType>
<Currency>USD</Currency>
<Charges>
<Fixed>
<Description>Dropoff Fee</Description>
<Currency>USD</Currency>
<Amount>0.0000</Amount>
<IsPrimary>false</IsPrimary>
<SemanticsCode>DROPOFFFEE</SemanticsCode>
<SemanticsVendorType>C</SemanticsVendorType>
</Fixed>
<RateWithAllowance>
<Currency>USD</Currency>
<Amount>44.0000</Amount>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<IsPrimary>true</IsPrimary>
<SemanticsCode>DAYS</SemanticsCode>
<SemanticsVendorType>C</SemanticsVendorType>
<PerUnit>DAY</PerUnit>
<NumUnits>1.0000</NumUnits>
<AllowanceNumUnits>250.0000</AllowanceNumUnits>
<AllowanceAmount>0.2400</AllowanceAmount>
<AllowanceIsUnlimited>false</AllowanceIsUnlimited>
</RateWithAllowance>
</Charges>
</Car>
</Segments>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>C123456789</RecordLocator>
<BookingSource>TravelBookings.com</BookingSource>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<ItinSourceName>ConcurConnectAPI</ItinSourceName>
<PassengerCount>1</PassengerCount>
</Booking>
<Booking>
<Segments>
<Hotel>
<Vendor>CQ</Vendor>
<Status>GK</Status>
<StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<ConfirmationNumber>3364214265</ConfirmationNumber>
<RateCode>LV4</RateCode>
<Name>CONCUR HOTEL</Name>
<HotelPropertyId>CONQ</HotelPropertyId>
<CheckinTime>03:00 PM</CheckinTime>
<CheckoutTime>12:00 PM</CheckoutTime>
<NumPersons>1</NumPersons>
<NumRooms>1</NumRooms>
<CancellationPolicy>Cxl 1 day prior to Arrival</CancellationPolicy>
<DailyRate>240.3500</DailyRate>
<Currency>USD</Currency>
<RoomDescription>1 KING BED ACCESSIBLE ROOM - K1RRC</RoomDescription>
<Charges>
<Rate>
<Currency>USD</Currency>
<Amount>240.3500</Amount>
<StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
<IsPrimary>false</IsPrimary>
<SemanticsCode>ROOMRATE</SemanticsCode>
<SemanticsVendorType>H</SemanticsVendorType>
<PerUnit>DAY</PerUnit>
<NumUnits>3.0000</NumUnits>
</Rate>
</Charges>
</Hotel>
</Segments>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>0987654321</RecordLocator>
<BookingSource>TravelBookings.com</BookingSource>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<OriginalItinLocator>33491211</OriginalItinLocator>
<ItinSourceName>ConcurConnectAPI</ItinSourceName>
<PassengerCount>1</PassengerCount>
</Booking>
</Bookings>
</Itinerary>
XML Example Request of Agency Proposal
POST https://www.concursolutions.com/api/travel/trip/v1.1?userid_type=login_id&userid_value=cm@example.com HTTPS/1.1
Authorization: OAuth {access token}
Content-Type: application/xml
...
<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
<ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
<ItinSourceName>ConcurConnectAPI</ItinSourceName>
<TripName>Trip from Dallas to Seattle</TripName>
<Comments />
<StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<BookedByFirstName>Chris</BookedByFirstName>
<BookedByLastName>Miller</BookedByLastName>
<TripStatus>7</TripStatus>
<TravelRequestId>3339</TravelRequestId>
<CustomAttributes>
<CustomAttribute>
<ExternalId />
<DataType>Numeric</DataType>
<Name>ProposalBatchSize</Name>
<DisplayTitle />
<Data>3</Data>
<DisplayOnItinerary>true</DisplayOnItinerary>
</CustomAttribute>
<CustomAttribute>
<ExternalId />
<DataType>Numeric</DataType>
<Name>ProposalSequenceIndex</Name>
<DisplayTitle />
<Data>1</Data>
<DisplayOnItinerary>true</DisplayOnItinerary>
</CustomAttribute>
</CustomAttributes>
<Bookings>
<Booking>
<Segments>
<Car>
<Vendor>CQ</Vendor>
<Status>HK</Status>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
<ConfirmationNumber>F1672664579</ConfirmationNumber>
<StartCityCode>SEA</StartCityCode>
<EndCityCode>SEA</EndCityCode>
<StartLocation>SEA</StartLocation>
<EndLocation>SEA</EndLocation>
<Class>E</Class>
<Body>C</Body>
<Transmission>M</Transmission>
<AirCondition>R</AirCondition>
<NumCars>1</NumCars>
<DiscountCode>346660</DiscountCode>
<DailyRate>44.0000</DailyRate>
<TotalRate>44.0000</TotalRate>
<RateType>D</RateType>
<Currency>USD</Currency>
<Charges>
<Fixed>
<Description>Dropoff Fee</Description>
<Currency>USD</Currency>
<Amount>0.0000</Amount>
<IsPrimary>false</IsPrimary>
<SemanticsCode>DROPOFFFEE</SemanticsCode>
<SemanticsVendorType>C</SemanticsVendorType>
</Fixed>
<RateWithAllowance>
<Currency>USD</Currency>
<Amount>44.0000</Amount>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<IsPrimary>true</IsPrimary>
<SemanticsCode>DAYS</SemanticsCode>
<SemanticsVendorType>C</SemanticsVendorType>
<PerUnit>DAY</PerUnit>
<NumUnits>1.0000</NumUnits>
<AllowanceNumUnits>250.0000</AllowanceNumUnits>
<AllowanceAmount>0.2400</AllowanceAmount>
<AllowanceIsUnlimited>false</AllowanceIsUnlimited>
</RateWithAllowance>
</Charges>
</Car>
</Segments>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>C123456789</RecordLocator>
<BookingSource>TravelBookings.com</BookingSource>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<ItinSourceName>ConcurConnectAPI</ItinSourceName>
<PassengerCount>1</PassengerCount>
</Booking>
<Booking>
<Segments>
<Hotel>
<Vendor>CQ</Vendor>
<Status>GK</Status>
<StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<ConfirmationNumber>3364214265</ConfirmationNumber>
<RateCode>LV4</RateCode>
<Name>CONCUR HOTEL</Name>
<HotelPropertyId>CONQ</HotelPropertyId>
<CheckinTime>03:00 PM</CheckinTime>
<CheckoutTime>12:00 PM</CheckoutTime>
<NumPersons>1</NumPersons>
<NumRooms>1</NumRooms>
<CancellationPolicy>Cxl 1 day prior to Arrival</CancellationPolicy>
<DailyRate>240.3500</DailyRate>
<Currency>USD</Currency>
<RoomDescription>1 KING BED ACCESSIBLE ROOM - K1RRC</RoomDescription>
<Charges>
<Rate>
<Currency>USD</Currency>
<Amount>240.3500</Amount>
<StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
<IsPrimary>false</IsPrimary>
<SemanticsCode>ROOMRATE</SemanticsCode>
<SemanticsVendorType>H</SemanticsVendorType>
<PerUnit>DAY</PerUnit>
<NumUnits>3.0000</NumUnits>
</Rate>
</Charges>
</Hotel>
</Segments>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>0987654321</RecordLocator>
<BookingSource>TravelBookings.com</BookingSource>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<OriginalItinLocator>33491211</OriginalItinLocator>
<ItinSourceName>ConcurConnectAPI</ItinSourceName>
<PassengerCount>1</PassengerCount>
</Booking>
</Bookings>
</Itinerary>
Post Itinerary Details Response
| HTTP Responses | Supported Content Types |
|---|---|
| HTTP Status Codes | application/xml |
Content Body
When the trip is created successfully, the request will return the full posted trip details with the following additional elements inside the Itinerary parent element:
| Element | Description |
|---|---|
| id | The URI containing the trip ID. |
| ItinLocator | The Itinerary Locator value (trip ID without the URL). The ItinLocator value is used when updating an existing trip. |
| DateModifiedUtc | The UTC formatted date that this booking was last modified. |
| BookedVia | The GDS the itinerary was booked in. |
| DateBookedLocal | The date, in the traveler's local time, that the booking was made. |
Agency Proposal
The response will include the CustomAttributes element and its child elements if the request was an Agency Proposal.
XML Example of Successful Response
<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
<id>https://www.concursolutions.com/api/travel/trip/v1.1/CNQR1234567890</id>
<ItinLocator>CNQR1234567890</ItinLocator>
<ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
<ItinSourceName>ConcurTravel</ItinSourceName>
<TripName>Trip from Dallas to Seattle</TripName>
<Comments />
<StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<BookedVia>EveryGDS</BookedVia>
<BookedByFirstName>Chris</BookedByFirstName>
<BookedByLastName>Miller</BookedByLastName>
<DateBookedLocal>2012-07-24T19:15:52</DateBookedLocal>
<Bookings>
<Booking>
<Segments>
<Car>
<Vendor>CQ</Vendor>
<Status>HK</Status>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
<ConfirmationNumber>F1672664579</ConfirmationNumber>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<StartCityCode>SEA</StartCityCode>
<EndCityCode>SEA</EndCityCode>
<StartLocation>SEA</StartLocation>
<EndLocation>SEA</EndLocation>
<Class>E</Class>
<Body>C</Body>
<Transmission>M</Transmission>
<AirCondition>R</AirCondition>
<NumCars>1</NumCars>
<DiscountCode>346660</DiscountCode>
<DailyRate>44.0000</DailyRate>
<TotalRate>44.0000</TotalRate>
<RateType>D</RateType>
<Currency>USD</Currency>
<Charges>
<Fixed>
<Description>Dropoff Fee</Description>
<Currency>USD</Currency>
<Amount>0.0000</Amount>
<IsPrimary>false</IsPrimary>
<SemanticsCode>DROPOFFFEE</SemanticsCode>
<SemanticsVendorType>C</SemanticsVendorType>
</Fixed>
<RateWithAllowance>
<Currency>USD</Currency>
<Amount>44.0000</Amount>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<IsPrimary>true</IsPrimary>
<SemanticsCode>DAYS</SemanticsCode>
<SemanticsVendorType>C</SemanticsVendorType>
<PerUnit>DAY</PerUnit>
<NumUnits>1.0000</NumUnits>
<AllowanceNumUnits>250.0000</AllowanceNumUnits>
<AllowanceAmount>0.2400</AllowanceAmount>
<AllowanceIsUnlimited>false</AllowanceIsUnlimited>
</RateWithAllowance>
</Charges>
</Car>
</Segments>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>C123456789</RecordLocator>
<BookingSource>ConcurCars</BookingSource>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<ItinSourceName>TravelSupplier</ItinSourceName>
<PassengerCount>1</PassengerCount>
</Booking>
<Booking>
<Segments>
<Hotel>
<Vendor>CQ</Vendor>
<Status>GK</Status>
<StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<ConfirmationNumber>3364214265</ConfirmationNumber>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<RateCode>LV4</RateCode>
<Name>CONCUR HOTEL</Name>
<HotelPropertyId>CONQ</HotelPropertyId>
<CheckinTime>00:00</CheckinTime>
<CheckoutTime>00:00</CheckoutTime>
<NumPersons>1</NumPersons>
<NumRooms>1</NumRooms>
<CancellationPolicy>Cxl 1 day prior to Arrival</CancellationPolicy>
<DailyRate>240.3500</DailyRate>
<Currency>USD</Currency>
<RoomDescription>1 KING BED ACCESSIBLE ROOM - K1RRC</RoomDescription>
<Charges>
<Rate>
<Currency>USD</Currency>
<Amount>240.3500</Amount>
<StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
<IsPrimary>false</IsPrimary>
<SemanticsCode>ROOMRATE</SemanticsCode>
<SemanticsVendorType>H</SemanticsVendorType>
<PerUnit>DAY</PerUnit>
<NumUnits>3.0000</NumUnits>
</Rate>
</Charges>
</Hotel>
</Segments>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>0987654321</RecordLocator>
<BookingSource>ConcurHotel</BookingSource>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<OriginalItinLocator>33491211</OriginalItinLocator>
<ItinSourceName>ConcurTravel</ItinSourceName>
<PassengerCount>1</PassengerCount>
</Booking>
</Bookings>
</Itinerary>
XML Example of Successful Response for Agency Proposal
<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
<id>https://www.concursolutions.com/api/travel/trip/v1.1/CNQR1234567890</id>
<ItinLocator>CNQR1234567890</ItinLocator>
<ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
<ItinSourceName>ConcurTravel</ItinSourceName>
<TripName>Trip from Dallas to Seattle</TripName>
<Comments />
<StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<BookedVia>EveryGDS</BookedVia>
<BookedByFirstName>Chris</BookedByFirstName>
<BookedByLastName>Miller</BookedByLastName>
<DateBookedLocal>2012-07-24T19:15:52</DateBookedLocal>
<Bookings>
<Booking>
<Segments>
<Car>
<Vendor>CQ</Vendor>
<Status>HK</Status>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
<ConfirmationNumber>F1672664579</ConfirmationNumber>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<StartCityCode>SEA</StartCityCode>
<EndCityCode>SEA</EndCityCode>
<StartLocation>SEA</StartLocation>
<EndLocation>SEA</EndLocation>
<Class>E</Class>
<Body>C</Body>
<Transmission>M</Transmission>
<AirCondition>R</AirCondition>
<NumCars>1</NumCars>
<DiscountCode>346660</DiscountCode>
<DailyRate>44.0000</DailyRate>
<TotalRate>44.0000</TotalRate>
<RateType>D</RateType>
<Currency>USD</Currency>
<Charges>
<Fixed>
<Description>Dropoff Fee</Description>
<Currency>USD</Currency>
<Amount>0.0000</Amount>
<IsPrimary>false</IsPrimary>
<SemanticsCode>DROPOFFFEE</SemanticsCode>
<SemanticsVendorType>C</SemanticsVendorType>
</Fixed>
<RateWithAllowance>
<Currency>USD</Currency>
<Amount>44.0000</Amount>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<IsPrimary>true</IsPrimary>
<SemanticsCode>DAYS</SemanticsCode>
<SemanticsVendorType>C</SemanticsVendorType>
<PerUnit>DAY</PerUnit>
<NumUnits>1.0000</NumUnits>
<AllowanceNumUnits>250.0000</AllowanceNumUnits>
<AllowanceAmount>0.2400</AllowanceAmount>
<AllowanceIsUnlimited>false</AllowanceIsUnlimited>
</RateWithAllowance>
</Charges>
</Car>
</Segments>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>C123456789</RecordLocator>
<BookingSource>ConcurCars</BookingSource>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<ItinSourceName>TravelSupplier</ItinSourceName>
<PassengerCount>1</PassengerCount>
</Booking>
<Booking>
<Segments>
<Hotel>
<Vendor>CQ</Vendor>
<Status>GK</Status>
<StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<ConfirmationNumber>3364214265</ConfirmationNumber>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<RateCode>LV4</RateCode>
<Name>CONCUR HOTEL</Name>
<HotelPropertyId>CONQ</HotelPropertyId>
<CheckinTime>00:00</CheckinTime>
<CheckoutTime>00:00</CheckoutTime>
<NumPersons>1</NumPersons>
<NumRooms>1</NumRooms>
<CancellationPolicy>Cxl 1 day prior to Arrival</CancellationPolicy>
<DailyRate>240.3500</DailyRate>
<Currency>USD</Currency>
<RoomDescription>1 KING BED ACCESSIBLE ROOM - K1RRC</RoomDescription>
<Charges>
<Rate>
<Currency>USD</Currency>
<Amount>240.3500</Amount>
<StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
<IsPrimary>false</IsPrimary>
<SemanticsCode>ROOMRATE</SemanticsCode>
<SemanticsVendorType>H</SemanticsVendorType>
<PerUnit>DAY</PerUnit>
<NumUnits>3.0000</NumUnits>
</Rate>
</Charges>
</Hotel>
</Segments>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>0987654321</RecordLocator>
<BookingSource>ConcurHotel</BookingSource>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<OriginalItinLocator>33491211</OriginalItinLocator>
<ItinSourceName>ConcurTravel</ItinSourceName>
<PassengerCount>1</PassengerCount>
</Booking>
</Bookings>
<CustomAttributes>
<CustomAttribute>
<ExternalId />
<DataType>Numeric</DataType>
<Name>ProposalBatchSize</Name>
<DisplayTitle />
<Data>3</Data>
<DisplayOnItinerary>true</DisplayOnItinerary>
</CustomAttribute>
<CustomAttribute>
<ExternalId />
<DataType>Numeric</DataType>
<Name>ProposalSequenceIndex</Name>
<DisplayTitle />
<Data>1</Data>
<DisplayOnItinerary>true</DisplayOnItinerary>
</CustomAttribute>
</CustomAttributes>
</Itinerary>
Post Itinerary Cancellation Request
| Description | Supported Content Types |
|---|---|
| Cancels all segments in the supplied trip. This endpoint can be used to cancel trips for a user that is not the OAuth consumer. This is most often done when a travel supplier or Travel Management Company needs to cancel a trip on behalf of a user. The supplier or TMC must be registered with SAP Concur and have an SAP Concur account with one of the following user roles: Web Services Administrator for Professional, or Can Administer for Standard. |
application/xml |
Query Parameters - Required
- cancel?{tripId}
The identifier for the desired trip and the cancel keyword.
Example:
https://www.concursolutions.com/api/travel/trip/v1.1/cancel?tripId={_tripId_}
Query Parameters - Optional
- userid_type=login_id&userid_value={loginID}
The SAP Concur loginID of the user that owns the trip. The userid_type and userid_value parameters can only be used if the OAuth consumer has the user role listed above.
Example:
https://www.concursolutions.com/api/travel/trip/v1.1/cancel?tripId={_tripId_}&userid_type=login_id&userid_value={_loginID_}
| Request Headers - Required | Request Headers - Optional |
|---|---|
| Authorization header with OAuth token for a valid SAP Concur user. The OAuth consumer must have one of the following user roles in SAP Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard. | None |
XML Example Request
POST /api/travel/trip/v1.1/cancel?tripId=CNQR1234567890 HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
...
POST Itinerary Cancellation
| HTTP Responses | Supported Content Types |
|---|---|
| HTTP Status Codes | application/xml |
Content Body
The request will return the full trip details for the cancelled trip. The trip will contain no segments, as those are all cancelled. The response includes the following additional elements inside the Itinerary parent element:
| Element | Description |
|---|---|
| id | The URI containing the trip ID. |
| ItinLocator | The Itinerary Locator value (trip ID without the URL). |
| ClientLocator | The identifier for the client. |
| DateModifiedUtc | The UTC formatted date that this booking was last modified. |
| BookedVia | The GDS the itinerary was booked in. |
| DateBookedLocal | The date, in the traveler's local time, that the booking was made. |
XML Example of Successful Response
<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
<id>https://www.concursolutions.com/api/travel/trip/v1.1/CNQR1234567890</id>
<ItinLocator>CNQR1234567890</ItinLocator>
<ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
<ItinSourceName>ConcurTravel</ItinSourceName>
<TripName>Trip from Dallas to Seattle</TripName>
<Comments />
<StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<BookedVia>EveryGDS</BookedVia>
<BookedByFirstName>Chris</BookedByFirstName>
<BookedByLastName>Miller</BookedByLastName>
<DateBookedLocal>2012-07-24T19:15:52</DateBookedLocal>
<Bookings>
<Booking>
<Segments/>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>C123456789</RecordLocator>
<BookingSource>ConcurCars</BookingSource>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<ItinSourceName>TravelSupplier</ItinSourceName>
<PassengerCount>1</PassengerCount>
</Booking>
<Booking>
<Segments/>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>0987654321</RecordLocator>
<BookingSource>ConcurHotel</BookingSource>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<OriginalItinLocator>33491211</OriginalItinLocator>
<ItinSourceName>ConcurTravel</ItinSourceName>
<PassengerCount>1</PassengerCount>
</Booking>
</Bookings>
</Itinerary>
POST Booking Details
Creates a new booking or updates an existing booking. A new booking will be assigned to the specified trip, or if no trip is specified, the first itinerary that spans the booking dates. If no trip is specified and no itinerary exists that spans the booking dates, a new itinerary will be created.
This endpoint can be used to create/update bookings for a user that is not the OAuth consumer. This is most often done when a travel supplier or Travel Management Company needs to create/update a booking on behalf of a user. The supplier or TMC must be registered with SAP Concur, and must have an account that has one of the following user roles: Web Services Administrator for Professional, or Can Administer for Standard.
POST /api/travel/booking/v1.0?tripId=12345678 HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Request Parameters
Query Parameters - Optional
- tripId={tripId} The unique identifier for the trip. Supplied in order to add a booking to an existing trip.
- userid_type=login_id&userid_value={loginID} The SAP Concur login ID of the user who owns the booking. Only provided when the booking owner is not the OAuth consumer. Can only be used when the OAuth consumer has the required user role.
Examples:
https://www.concursolutions.com/api/travel/booking/v1.1?tripId={tripId}
https://www.concursolutions.com/api/travel/booking/v1.1?userid_type=login_id&userid_value={loginID}
Request Body Root Elements
The request contains a Booking parent element with the following child elements:
| Required Element | Description |
|---|---|
| BookingSource | The supplier's name. |
| ItinSourceName | The itinerary source. Format: TravelSupplier |
| RecordLocator | Record locator for this booking. This is often six alphanumeric characters but can have other formats depending on the booking source |
| Optional Element | Description |
|---|---|
| DateBookedLocal | The date the booking was created, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss |
| FormOfPaymentName | The name of the form of payment for the booking. |
| FormOfPaymentType | The type of the form of payment. |
| TicketMailingAddress | The mailing address for the booked ticket, if available. |
| TicketPickupLocation | The pickup location for the booked ticket, if available |
| TicketPickupNumber | The confirmation number to pick up the booked ticket, if available. |
| AirfareQuotes | List of stored airfare quotes for this booking. |
| AirlineTickets | List of Airline Tickets for this booking. |
| Charges | List of Charges for this booking. |
| MiscChargeOrders | List of Miscellaneous AirCharges for this booking. |
| Passengers | The Passengers element contains child element for each booked passenger. The description of each child element can be seen in a subsequent table. |
| PassPrograms | List of Pass Programs for this booking. |
| PhoneNumbers | List of Phone numbers associated with this booking. |
| RailPayments | List of Rail payments associated with rail segments in this booking. |
| Segments | List of Segments in this booking. This parent element contains one or more Air, Car, Hotel, Dining, Ride, Rail, Parking, or Event parent elements for the booking. |
| Delivery | The method this booking was delivered. |
| WaitListSegments | The segments that the traveler is waitlisted for this booking. |
| Warnings | The warnings associated with the booking. |
| WebAddresses | List of web addresses such as emails, pickup URLs, etc. associated with this booking |
| BookingReferrer | BookingReferrer is used only in specific source tracking scenarios when there is a need to distinguish between bookings with the same BookingSources coming through different flows. Do not populate without coordinating with your technical contact. The supported values are: Concur Travel, Sign-in with SAP Concur, Supplier Mobile, Supplier Web |
Passenger Child Elements
| Required Element | Description |
|---|---|
| NameFirst | The first name of the passenger. |
| NameLast | The last name of the passenger. |
| Optional Element | Description |
|---|---|
| NameMiddle | The middle name of the passenger. |
| NamePrefix | The name prefix of the passenger. |
| NameRemark | Additional details about the passenger's name. |
| NameSuffix | The name suffix of the passenger. |
| NameTitle | The title of the passenger. |
| TextName | The user's full name as entered in the booking tool if different from the name in the database. |
| FrequentTravelerProgram | Passenger's loyalty programs |
Response
This function returns the full trip details.
If the end user updates an existing reservation which results in a new confirmation number, the old booking must be explicitly cancelled in addition to posting the new booking to SAP Concur. If the previous booking is not cancelled, the user will see both bookings in their SAP Concur trip list.
Examples
Example 1: XML Example Request
POST /api/travel/booking/v1.0?tripId=12345678 HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Content-Type: application/xml
...
<Booking xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Segments>
<Car>
<Vendor>AL</Vendor>
<VendorName>Alamo</VendorName>
<Status>HK</Status>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<EndDateLocal>2013-12-23T12:00:00</EndDateLocal>
<StartDateUtc>2013-12-21T20:00:00</StartDateUtc>
<EndDateUtc>2013-12-23T20:00:00</EndDateUtc>
<ConfirmationNumber>F16726AIUS</ConfirmationNumber>
<DateCreatedUtc>2012-07-22T11:55:42</DateCreatedUtc>
<DateModifiedUtc>2012-07-22T11:55:42</DateModifiedUtc>
<StartCityCode>SEA</StartCityCode>
<EndCityCode>SEA</EndCityCode>
<StartLocation>SEA</StartLocation>
<EndLocation>SEA</EndLocation>
<Class>E</Class>
<Body>C</Body>
<Transmission>A</Transmission>
<AirCondition>R</AirCondition>
<NumPersons>1</NumPersons>
<NumCars>1</NumCars>
<DiscountCode>4321</DiscountCode>
<DailyRate>35.0000</DailyRate>
<TotalRate>105.0000</TotalRate>
<RateType>D</RateType>
<Currency>USD</Currency>
</Car>
</Segments>
<RecordLocator>PANAMA50</RecordLocator>
<BookingSource>Alamo</BookingSource>
<DateCreatedUtc>2012-07-22T11:55:42</DateCreatedUtc>
<DateModifiedUtc>2012-07-22T11:55:42</DateModifiedUtc>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<ItinSourceName>TravelSupplier</ItinSourceName>
<Passengers>
<Passenger>
<PassengerKey>0</PassengerKey>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
</Booking>
Example 2: XML Example of Successful Response
<Itinerary xmlns="https://www.concursolutions.com/api/travel/trip/2010/06">
<id>https://www.concursolutions.com/api/travel/trip/v1.1/CNQR1234567890</id>
<ItinLocator>CNQR1234567890</ItinLocator>
<ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
<ItinSourceName>TravelSupplier</ItinSourceName>
<TripName>Trip to Seattle</TripName>
<Comments />
<StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
<EndDateLocal>2013-12-23T23:59:00</EndDateLocal>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<BookedVia>EveryGDS</BookedVia>
<BookedByFirstName>Chris</BookedByFirstName>
<BookedByLastName>Miller</BookedByLastName>
<DateBookedLocal>2012-07-24T19:15:52</DateBookedLocal>
<Booking>
<Segments>
<Car>
<Vendor>AL</Vendor>
<VendorName>Alamo</VendorName>
<Status>HK</Status>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<EndDateLocal>2013-12-23T12:00:00</EndDateLocal>
<StartDateUtc>2013-12-21T20:00:00</StartDateUtc>
<EndDateUtc>2013-12-23T20:00:00</EndDateUtc>
<ConfirmationNumber>F16726AIUS</ConfirmationNumber>
<DateCreatedUtc>2012-07-22T11:55:42</DateCreatedUtc>
<DateModifiedUtc>2012-07-22T11:55:42</DateModifiedUtc>
<StartCityCode>SEA</StartCityCode>
<EndCityCode>SEA</EndCityCode>
<StartLocation>SEA</StartLocation>
<EndLocation>SEA</EndLocation>
<Class>E</Class>
<Body>C</Body>
<Transmission>A</Transmission>
<AirCondition>R</AirCondition>
<NumPersons>1</NumPersons>
<NumCars>1</NumCars>
<DiscountCode>4321</DiscountCode>
<DailyRate>35.0000</DailyRate>
<TotalRate>105.0000</TotalRate>
<RateType>D</RateType>
<Currency>USD</Currency>
</Car>
</Segments>
<RecordLocator>PANAMA50</RecordLocator>
<BookingSource>Alamo</BookingSource>
<DateCreatedUtc>2012-07-22T11:55:42</DateCreatedUtc>
<DateModifiedUtc>2012-07-22T11:55:42</DateModifiedUtc>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<ItinSourceName>TravelSupplier</ItinSourceName>
<Passengers>
<Passenger>
<PassengerKey>0</PassengerKey>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
</Booking>
</Itinerary>
POST Booking Cancellation
Cancels an existing booking. By default, the OAuth consumer should be the owner of the booking. This endpoint can also be used to cancel bookings that the OAuth consumer does not own. This is most often done when a Travel Management Company needs to cancel bookings on behalf of a user. The TMC must be registered with SAP Concur and have an SAP Concur account that has one of the following user roles: Web Services Administrator for Professional, or Can Administer for Standard.
NOTE:
Booking records can only be updated by the booking source that created them. SAP Concur verifies the source information before processing the request.
POST /api/travel/booking/v1.1/cancel?bookingSource={FastTravel}&confirmationNumber={098765431} HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Request Parameters
Query Parameters - Required
- cancel?bookingSource={Supplier}
The cancel keyword and the unique identifier for the supplier, configured by SAP Concur during the application review. The bookingSource must match the Supplier Name associated with the booking.
- confirmationNumber={confnum}
The confirmation number for the booking to cancel.
Example:
https://www.concursolutions.com/api/travel/booking/v1.1/cancel?bookingSource={Supplier}&confirmationNumber={confnum}
Query Parameters - Optional
- userid_type=login_id&userid_value={loginID}
The SAP Concur login ID of the user who owns the booking. Only provided when the booking owner is not the OAuth consumer. Can only be used when the OAuth consumer has the required user role.
Example:
https://www.concursolutions.com/api/travel/booking/v1.1/cancel?bookingSource={Supplier}&confirmationNumber={confnum}&userid_type=login_id&userid_value={loginID}
Content Type
application/xml
Authorization Header
The authorization header must have an OAuth token for a valid SAP Concur user. The OAuth consumer must be registered as a Supplier or TMC with SAP Concur, and must have one of the following user roles in SAP Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard.
Response
This function returns the full booking details. If the booking is not found, the function returns a HTTP 404 error and the following element:
Status: This element contains the value: NotFound.
Examples
Examples 1: XML Example Request
POST /api/travel/booking/v1.1/cancel?bookingSource={FastTravel}&confirmationNumber={098765431} HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Examples 2: XML Example of Successful Response
<Car>
<Vendor>ZE</Vendor>
<Status>HK</Status>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
<TimeZoneId xsi:nil="true"/>
<StartDateUtc>2013-12-21T20:00:00</StartDateUtc>
<EndDateUtc>2013-12-24T20:00:00</EndDateUtc>
<ConfirmationNumber>0987654321</ConfirmationNumber>
<CancellationNumber>1029384756</CancellationNumber>
<DateCreatedUtc>2012-07-22T11:55:42</DateCreatedUtc>
<DateCancelledUtc>2012-07-25T14:21:35</DateCancelledUtc>
<DateModifiedUtc>2012-07-22T11:55:42</DateModifiedUtc>
<UpgradedDateTime xsi:nil="true"/>
<IsUpgradeAllowed xsi:nil="true"/>
<FrequentTravelerId/>
<StartCityCode>SEA</StartCityCode>
<EndCityCode>SEA</EndCityCode>
<StartLocation>SEA</StartLocation>
<EndLocation>SEA</EndLocation>
<Class>E</Class>
<Body>C</Body>
<Transmission>M</Transmission>
<AirCondition>R</AirCondition>
<PhoneNumber/>
<NumPersons xsi:nil="true"/>
<NumCars>1</NumCars>
<DiscountCode>346660</DiscountCode>
<Charges>
<Fixed>
<Description>Dropoff Fee</Description>
<Currency>USD</Currency>
<Amount>0.0000</Amount>
<StartDateLocal xsi:nil="true"/>
<IsPaid xsi:nil="true"/>
<SemanticsCode>DROPOFFFEE</SemanticsCode>
<SemanticsVendorType>C</SemanticsVendorType>
</Fixed>
<RateWithAllowance>
<Currency>USD</Currency>
<Amount>44.0000</Amount>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<IsPaid xsi:nil="true"/>
<SemanticsCode>DAYS</SemanticsCode>
<SemanticsVendorType>C</SemanticsVendorType>
<PerUnit>DAY</PerUnit>
<NumUnits>1.0000</NumUnits>
<AllowanceUnit/>
<AllowanceNumUnits>250.0000</AllowanceNumUnits>
<AllowanceAmount>0.2400</AllowanceAmount>
<AllowanceIsUnlimited>false</AllowanceIsUnlimited>
</RateWithAllowance>
</Charges>
<Remarks/>
<PerDiemLocation/>
</Car>
Booking Object Elements
The booking elements contain many child elements. For ease of use, these elements are divided into the Core Elements, which are the most frequently used, and Additional Elements, which are not often used but are supported by the Itinerary web service. Some elements only appear if the travel supplier created the booking. Elements are marked as required if they must be supplied for a new booking.
NOTE: TripLink - Open Booking suppliers see a targeted subset of these fields. Refer to the documentation here for the TripLink - Open Booking supplier booking object elements.
Air Booking Elements
Core Elements - Required
| Element | Description |
|---|---|
| ClassOfService | The class of the booking. |
| ConfirmationNumber | The record locator or confirmation number for the flight from the airline. |
| EndCityCode | The IATA airport code for the end city of the booking. |
| EndDateLocal | The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss |
| FlightNumber | The flight number for the booking. |
| StartCityCode | The IATA airport code for the starting address for the booking. |
| StartDateLocal | The booking starting time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss |
| Vendor | The two letter GDS vendor code. Use $$ when not available. |
Core Elements - Optional
| Element | Description |
|---|---|
| CancellationNumber | The cancellation number from the vendor. This field should be set when you cancel a segment. |
| CancellationPolicy | The cancellation policy from the vendor. |
| Charges | The charges for this booking. Refer to the Charges Child Elements table. |
| DateCancelledUtc | The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| DateCreatedUtc | The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| DateModifiedUtc | The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| EndDateUtc | The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| EndGate | The arrival gate for the booking. |
| EndTerminal | The arrival terminal for the booking. |
| LegId | The leg ID of the booking. Leg IDs do not change on a connection. For each unique leg ID in the trip, all flights subsequent to the first segment with the same leg ID are connections. |
| Seats | The seats for the booking. This parent element contains an AirSeat element for each included seat. The AirSeat element contains the following child elements: PassengerRph - The passenger assigned to the seat. SeatNumber - The number of the seat. |
| StartDateUtc | The booking starting time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| StartGate | The departure gate for the booking. |
| StartTerminal | The departure terminal for the booking. |
| Status | The GDS based booking status for the segment such as HK, HL, BK, etc. |
| TimeZone | The time zone of the booking. Format: One of the supported Olson or Windows Time Zones. |
Additional Elements - Optional
| Element | Description |
|---|---|
| AircraftCode | The code for the aircraft type. |
| Bags | The number of bags included in the booking. |
| Cabin | The section of the airplane for the booking. |
| CarbonEmissionLbs | The pounds of carbon emission for this booking. |
| CarbonModel | The model used to calculate the carbon emissions. |
| CheckedBaggage | Whether the booking includes checked baggage. |
| Duration | The duration of the booked flight. |
| ETicket | Whether the booking has an e-ticket. Format: Y/N |
| IsOpenSegment | Whether the segment is open. Format: True/False |
| IsPreferredVendor | If the airline is marked as a preferred property by the company. Format: True/False |
| IsUpgradeAllowed | Whether the booking can be upgraded. Format: True/False |
| Meals | The meals included in the booking. |
| Miles | The number of miles included in the booking. |
| Notes | Additional details about the booking. |
| OpenSegment | Additional information about the open segment. |
| OperatedByFlightNumber | Flight Number provided by the airline operating the flight on behalf of the booked airline. |
| OperatedByVendor | The airline operating the flight on behalf of the booked airline. |
| OperatedByVendorName | The name of the airline operating the flight on behalf of the booked airline. |
| Services | The services included in the booking. |
| SpecialInstructions | Additional instructions regarding the booking. Max Length: 256 |
| UpgradedDateTime | The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss |
Car Booking Elements
Core Elements - Required
| Element | Description |
|---|---|
| ConfirmationNumber | The confirmation number from the vendor. |
| EndDateLocal | The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss |
| StartDateLocal | The booking starting time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss |
| Vendor | The two letter GDS vendor code. |
Core Elements - Optional
| Element | Description |
|---|---|
| CancellationNumber | The cancellation number from the vendor. This field should be set when you cancel a segment. |
| CancellationPolicy | The cancellation policy from the vendor. |
| Charges | The charges for this booking. Refer to the Charges Child Elements table. |
| Currency | The 3-letter ISO 4217 currency code for the booking. |
| DailyRate | The daily rate for the booking. |
| DateCancelledUtc | The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| DateCreatedUtc | The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| DateModifiedUtc | The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| EndCityCode | The IATA airport code for the ending address for the booking. |
| EndDateUtc | The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| EndLatitude | The latitude for the ending location of the booking. |
| EndLongitude | The longitude for the ending location of the booking. |
| Notes | Additional information about the booking. |
| PhoneNumber | The phone number for the user. |
| RateCode | The rate code for the booking. |
| StartCityCode | The IATA airport code for the starting address for the booking. |
| StartDateUtc | The booking starting time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| StartLatitude | The latitude for the starting location of the booking. |
| StartLongitude | The longitude for the starting location of the booking. |
| Status | The booking status. |
| TimeZone | The time zone of the booking. Format: One of the supported Olson or Windows Time Zones. |
| TotalRate | The total rate amount of the booking. |
| VendorName | The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary. |
Additional Elements - Optional
| Element | Description |
|---|---|
| AirCondition | The character code that indicates if car has an air conditioner. R for AC, N for No AC |
| Body | The character code to indicate how many passengers the car can seat. |
| Class | Character code to indicate the class of the car e.g. if it is economy, full size, compact, etc. Varies by Vendor |
| DiscountCode | The discount code used by the company/TMC to get a discounted rate. |
| DropoffCollectionAddress1 | The AddressLine1 for the dropoff address when the rental service offers dropoff. |
| DropoffCollectionAddressType | |
| DropoffCollectionCategory | |
| DropoffCollectionCity | City for the dropoff address when the rental service offers dropoff. |
| DropoffCollectionCityCode | The IATA airport code for the dropoff address when the rental service offers dropoff. |
| DropoffCollectionCountry | The country for the dropoff address when the rental service offers dropoff. |
| DropoffCollectionLatitude | The latitude for the dropoff address when the rental service offers dropoff. |
| DropoffCollectionLongitude | The longitude for the dropoff address when the rental service offers dropoff. |
| DropoffCollectionNumber | |
| DropoffCollectionPhoneNumber | The phone number for the dropoff address when the rental service offers dropoff. |
| DropoffCollectionPostalCode | The postal code for the dropoff address when the rental service offers dropoff. |
| DropoffCollectionState | The state for the dropoff address when the rental service offers dropoff. |
| EndAddress | The ending address for the booking. |
| EndAddress2 | The ending address for the booking. |
| EndCity | The ending address for the booking. |
| EndCloseTime | The closing time for the dropoff location. |
| EndCountry | The ending address for the booking. |
| EndLocation | The dropoff location. |
| EndOpenTime | The opening time of the dropoff location. |
| EndPhoneNumber | The phone number of the dropoff location. |
| EndPostalCode | The ending address for the booking. |
| EndState | The ending address for the booking. |
| FrequentTravelerId | The loyalty program ID for the user. |
| IsUpgradeAllowed | Whether the booking can be upgraded. Format: True/False |
| NumCars | The number of cars rented. |
| NumPersons | The number of people including the driver that the rental is for. |
| PickupDeliveryAddress1 | The AddressLine1 for the pickup address when the rental service offers pickup. |
| PickupDeliveryAddressType | |
| PickupDeliveryCategory | |
| PickupDeliveryCity | The city for the pickup address when the rental service offers pickup. |
| PickupDeliveryCityCode | The IATA airport code for the pickup address when the rental service offers pickup. |
| PickupDeliveryCountry | The country for the pickup address when the rental service offers pickup. |
| PickupDeliveryLatitude | The latitude for the pickup address when the rental service offers pickup. |
| PickupDeliveryLongitude | The longitude for the pickup address when the rental service offers pickup. |
| PickupDeliveryNumber | |
| PickupDeliveryPhoneNumber | The phone number for the pickup address when the rental service offers pickup. |
| PickupDeliveryPostalCode | The postal code for the pickup address when the rental service offers pickup. |
| PickupDeliveryState | The state for the pickup address when the rental service offers pickup. |
| RateType | The rate type for the booking. |
| SpecialEquipment | Any special equipment required by the renter. |
| SpecialInstructions | Additional instructions regarding the booking. Max Length: 256 |
| StartAddress | The starting address of the booking. |
| StartAddress2 | The starting address for the booking. |
| StartCity | The starting address for the booking. |
| StartCloseTime | The closing time for the pickup location. |
| StartCountry | The starting address for the booking. |
| StartLocation | The starting location of the booking. |
| StartOpenTime | The opening time for the pickup location. |
| StartPostalCode | The starting address for the booking. |
| StartState | The starting address for the booking. |
| Transmission | The character code that indicates if the car has auto-transmission. A for Auto, M for Manual |
| UpgradedDateTime | The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss |
Hotel Booking Elements
Core Elements - Required
| Element | Description |
|---|---|
| ConfirmationNumber | The confirmation number from the vendor. |
| EndDateLocal | The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss |
| Name | The hotel name for the booking. |
| StartCityCode | The IATA airport code for the starting address for the booking. |
| StartDateLocal | The booking starting time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss |
| Status | The booking status. |
| Vendor | The two letter GDS vendor code. |
Core Elements - Optional
| Element | Description |
|---|---|
| CancellationNumber | The cancellation number from the vendor. This field should be set when you cancel a segment. |
| CancellationPolicy | The cancellation policy from the vendor. |
| Charges | The charges for this booking. Refer to the Charges Child Elements table. |
| CheckinTime | The check in time for the hotel booking. |
| CheckoutTime | The check out time for the hotel booking. |
| Currency | The 3-letter ISO 4217 currency code for the booking. |
| DailyRate | Average per day rate for the hotel. If the rate varies over the duration, it can be specified using the charges model. |
| DateCancelledUtc | The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| DateCreatedUtc | The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| DateModifiedUtc | The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| EndDateUtc | The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| HotelPropertyId | The hotel's property ID. |
| Notes | Additional information about the booking. |
| NumPersons | The number of people the booking is for. |
| NumRooms | The number of rooms the booking is for. |
| PhoneNumber | The phone number for the booking. |
| RateCode | The rate code for the booking. |
| RoomDescription | The room description for the booking. Max Length: 200 |
| RoomType | The room type for the booking. |
| SpecialInstructions | Additional instructions regarding the booking. Max Length: 256 |
| StartAddress | The starting address of the booking. |
| StartAddress2 | The starting address for the booking. |
| StartCity | The starting address for the booking. |
| StartCountry | The starting address for the booking. |
| StartLatitude | The latitude for the starting location of the booking. |
| StartLongitude | The longitude for the starting location of the booking. |
| StartPostalCode | The starting address for the booking. |
| StartState | The starting address for the booking. |
| StartDateUtc | The booking starting time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| TimeZone | The time zone of the booking. Format: One of the supported Olson or Windows Time Zones. |
| TotalRate | The total rate amount of the booking. |
Additional Elements - Optional
| Element | Description |
|---|---|
| EndCityCode | The IATA airport code for the ending address for the booking. |
| DiscountCode | The discount code for the booking. |
| FrequentTravelerId | The traveler’s ID for the frequent traveler reward program. |
| HadDeposit | Whether the booking had a deposit. Format: true/false |
| IsUpgradeAllowed | Whether the booking can be upgraded. Format: true/false |
| ModificationCode | The code for the modification to the booking. |
| PartnerMembershipId | The membership ID of the partner associated with the booking. |
| PassiveType | The type of the booking. |
| RateAccess | The rate access for the booking. |
| RateType | The rate type for the booking. |
| UpgradedDateTime | The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss |
| VendorFlags | Semi-colon-delimited list of flags for free hotel service flags. E.g. free breakfast (FB), internet (FI), Parking (FP), etc. If they were all present they can be concatenated as - FB;FI;FP; |
| VendorName | The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary. |
Dining Booking Elements
Core Elements - Required
| Element | Description |
|---|---|
| ConfirmationNumber | The confirmation number from the vendor. |
Core Elements - Optional
| Element | Description |
|---|---|
| CancellationNumber | The cancellation number from the vendor. This field should be set when you cancel a segment. |
| Charges | The charges for this booking. Refer to the Charges Child Elements table. |
| DateCancelledUtc | The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| DateCreatedUtc | The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| DateModifiedUtc | The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| EndDateLocal | The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss |
| EndDateUtc | The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| FrequentTravelerId | The loyalty program ID for the user. |
| IsUpgradeAllowed | Whether the booking can be upgraded. Format: true/false |
| Name | The name of the restaurant. Maximum length: 80 |
| Notes | Additional information about the booking. |
| NumPersons | The number of persons for the booking. |
| PhoneNumber | The restaurant phone number. |
| RestaurantId | The booking vendor’s restaurant ID. Maximum length: 50 |
| StartAddress | The restaurant address. Maximum length: 80 |
| StartAddress2 | The restaurant address. Maximum length: 80 |
| StartCity | The restaurant address. Maximum length: 50 |
| StartCountry | The restaurant address. |
| StartDateLocal | The booking starting time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss |
| StartDateUtc | The booking starting time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| StartLatitude | The latitude of the restaurant. |
| StartLongitude | The longitude of the restaurant. |
| StartPostalCode | The restaurant address. Maximum length: 24 |
| StartState | The restaurant address. Maximum length: 50 |
| Status | The status of the segment. |
| TimeZone | The time zone of the booking. Format: One of the supported Olson or Windows Time Zones. |
| UpgradedDateTime | The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss |
| Vendor | The two letter GDS vendor code. |
| VendorName | The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary. |
Ride Booking Elements
Core Elements - Required
| Element | Description |
|---|---|
| ConfirmationNumber | The confirmation number from the vendor. |
| EndCityCode | The ending IATA airport code of the booking. |
| StartCityCode | The starting IATA airport code of the booking. |
| Vendor | The two letter GDS vendor code. One of the following vendor codes: |
Vendor Codes
| Code | Description |
|---|---|
| $R | RideCharge |
| AL | AddisonLee |
| DG | DeemGroundLimo |
| GC | GroundScope |
| GS | GroundSpan |
| LC | Limoscom |
| SQ | SummitQwest |
| SW | SummitQwest |
| TD | Tandem |
| TV | Transvip |
| $$ | unknown |
Core Elements - Optional
| Element | Description |
|---|---|
| CancellationNumber | The cancellation number from the vendor. This field should be set when you cancel a segment. |
| CancellationPolicy | The cancellation policy from the vendor. |
| Currency | The 3-letter ISO 4217 currency code for the booking. |
| DateCancelledUtc | The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| DateCreatedUtc | The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| DateModifiedUtc | The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| DropoffInstructions | Instructions regarding the booking. |
| Duration | The duration of the booking. |
| EndAddress | The ending address of the booking. |
| EndAddress2 | The ending address of the booking. |
| EndCity | The ending address of the booking. |
| EndCountry | The ending address of the booking. |
| EndDateLocal | The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss |
| EndDateUtc | The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| EndLatitude | The latitude for the ending location of the booking. |
| EndLocation | The ending location of the booking. |
| EndLocationCode | The ending location code of the booking. |
| EndLocationName | The ending location name of the booking. |
| EndLongitude | The longitude of the ending point of the booking. |
| EndPostalCode | The ending address of the booking. |
| EndState | The ending address of the booking. |
| IsPersonal | Whether the segment is for personal travel. Format: true/false. |
| IsUpgradeAllowed | Whether the booking can be upgraded. Format: true/false |
| MeetingInstructions | The instructions for the meeting location of the booking. |
| Miles | The number of miles for the booking. |
| Name | The name on the booking. |
| Notes | Additional information about the booking. |
| NumberOfHours | The number of hours of the booking. |
| NumPersons | The number of people included in the booking. |
| OperatedByVendor | The operated by vendor for the booking. |
| PassiveCityCode | The passive city code of the booking. |
| PhoneNumber | The ride vendor phone number. |
| PickupInstructions | Instructions regarding the booking. |
| Rate | The rate for the booking. |
| RateDescription | The rate description for the booking. |
| RateNotes | The rate notes for the booking. |
| RateType | The rate type for the booking. |
| ReservationId | The booking vendor’s reservation ID. |
| SpecialInstructions | The special instructions for the ride. Max Length: 256 |
| StartAddress | The starting address of the booking. |
| StartAddress2 | The starting address of the booking. |
| StartCity | The starting address of the booking. |
| StartCountry | The starting address of the booking. |
| StartDateLocal | The booking starting time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss |
| StartDateUtc | The booking starting time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| StartLatitude | The latitude of the booking start location. |
| StartLocation | The starting location of the booking. |
| StartLocationCode | The code of the starting location of the booking. |
| StartLocationName | The name of the starting location of the booking. |
| StartLongitude | The longitude of the booking start location. |
| StartPostalCode | The starting address of the booking. |
| StartState | The starting address of the booking. |
| Status | The status of the segment. |
| TimeZone | The time zone of the booking. Format: One of the supported Olson or Windows Time Zones. |
| UpgradedDateTime | The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss |
| VendorName | The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary. |
| Charges | The charges for this booking. Refer to the Charges Child Elements table. |
Rail Booking Elements
Core Elements - Required
| Element | Description |
|---|---|
| ConfirmationNumber | The confirmation number from the vendor. |
| StartDateLocal | The starting date of travel for this segment, in the local time of to the starting point. Format: YYYY-MM-DDThh:mm:ss |
Core Elements - Optional
| Element | Description |
|---|---|
| Amenities | The booked amenities. |
| Cabin | The cabin identifier. |
| CancellationNumber | The cancellation number from the vendor. This field should be set when you cancel a segment. |
| CarbonEmissionLbs | The pounds of carbon emission for this booking. |
| CarbonModel | The model used to calculate the carbon emissions. |
| ClassOfService | The class of the booking. |
| Currency | The 3-letter ISO 4217 currency code for the booking. |
| DateCancelledUtc | The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| DateCreatedUtc | The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| DateModifiedUtc | The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| DiscountCode | The discount code for the booking. |
| Duration | The duration of the trip booked. |
| EndCity | The end city for the rail trip. |
| EndCityCode | The IATA airport code for the end city of the trip. |
| EndCountry | The country code for the booking. |
| EndDateLocal | The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss |
| EndDateUtc | The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| EndLatitude | The latitude of the ending point of the booking. |
| EndLongitude | The longitude of the ending point of the booking. |
| EndPlatform | The ending platform location of the booking. |
| EndRailStation | The code for the ending station of the booking. |
| EndRailStationName | The name of the ending station of the booking. |
| ETicket | The e-ticket number. |
| FareType | The type of fare on the rail booking. |
| FrequentTravelerId | The traveler’s ID for the frequent traveler reward program. |
| IsUpgradeAllowed | Whether the booking can be upgraded. Format: true/false |
| LegId | The trip leg ID. |
| Meals | The booked meals. |
| Miles | The number of miles booked. |
| Notes | Additional information about the booking. |
| NumPersons | The number of persons booked for the trip. |
| NumStops | The number of stops in the booking. |
| OperatedByTrainNumber | The train identifier of the operating vendor of the booked trip. |
| OperatedByVendor | The operating vendor of the booked trip. |
| RateCode | The vendor's code for the rate of the booking. |
| RouteRestrictCode | The code to restrict the route of the booking. |
| SpecialInstructions | The instructions for the booking. Max Length: 256 |
| StartCity | The starting city of the booking. |
| StartCityCode | The IATA airport code for the starting city of the booking. |
| StartCountry | The starting country of the booking. |
| StartDateUtc | The starting date of travel for this segment, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| StartLatitude | The latitude of the starting location of the booking. |
| StartLongitude | The longitude of the starting location of the booking. |
| StartPlatform | The starting platform location of the booking. |
| StartRailStation | The code of the starting station of the booking. |
| StartRailStationName | The name of the starting station of the booking. |
| Status | The booking status. |
| TimeZone | The time zone of the booking. Format: One of the supported Olson or Windows Time Zones. |
| TotalRate | The total rate amount of the booking. |
| TrainNumber | The number for the booked train. |
| TrainTypeCode | The code for the type of train used in the booking. |
| TrainTypeName | The name of the type of train used in the booking. |
| TransportMode | The transport mode of the booking. |
| UpgradedDateTime | The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss |
| Vendor | The two letter GDS vendor code. |
| VendorName | The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary. |
| WagonNumber | The wagon number of the train car. |
| Charges | The charges for this booking. Refer to the Charges Child Elements table. |
| Seats | The booked seats. This parent element contains a RailSeat element for each included seat. The RailSeat element has the following child elements: |
RailSeat Child Elements
| Element | Description |
|---|---|
| Amenities | The amenities for the seat. |
| BerthPosition | The berth location of the seat. |
| Deck | Which deck the seat is on. |
| FacingForward | Whether the seat is facing forward. |
| FareSpaceComfort | The space around the seat. |
| PassengerRph | Which passenger the seat is assigned to. |
| SeatNumber | The number of the seat. |
| SeatPosition | The location of the seat. |
| SpaceType | The type of space around the seat. |
| Status | The status of the seat booking. |
| WagonNumber | The number of the wagon the seat is on. |
| WagonType | The type of wagon the seat is on. |
Parking Booking Elements
Core Elements - Required
| Element | Description |
|---|---|
| ConfirmationNumber | The confirmation number from the vendor. |
| StartDateLocal | The starting date of travel for this segment, in the local time of to the starting point. Format: YYYY-MM-DDThh:mm:ss |
Core Elements - Optional
| Element | Description |
|---|---|
| CancellationNumber | The cancellation number from the vendor. This field should be set when you cancel a segment. |
| ClassOfService | The class of the booking. |
| Currency | The 3-letter ISO 4217 currency code for the booking. |
| DateCancelledUtc | The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| DateCreatedUtc | The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| DateModifiedUtc | The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| EndDateLocal | The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss |
| EndDateUtc | The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| FrequentTravelerId | The traveler’s ID for the frequent traveler reward program. |
| IsUpgradeAllowed | Whether the booking can be upgraded. Format: true/false |
| Notes | Additional information about the booking. |
| OperatedByVendor | The operating vendor of the booking. |
| ParkingLocationId | The location of the parking booking. |
| PhoneNumber | The parking phone number. |
| Pin | The PIN number for the booking. |
| RateCode | The vendor's code for the rate of the booking. |
| StartAddress | The starting address of the booking. |
| StartAddress2 | The starting address of the booking. |
| StartCity | The starting address of the booking. |
| StartCityCode | The IATA airport code for the starting city of the booking. |
| StartCountry | The starting address of the booking. |
| StartDateUtc | The starting date of travel for this segment, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| StartLocation | The parking location. |
| StartPostalCode | The starting address of the booking. Maximum length: 24 |
| StartState | The starting address of the booking. Maximum length: 50 |
| Status | The booking status. |
| TimeZone | The time zone of the booking. Format: One of the supported Olson or Windows Time Zones. |
| TotalRate | The total rate amount of the booking. |
| UpgradedDateTime | The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss |
| Vendor | The two letter GDS vendor code. |
| VendorName | The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary. |
| Charges | The charges for this booking. Refer to the Charges Child Elements table. |
Travel Booking
NOTE: This booking type is used by the Concur Travel Request product to store the main destination for the trip without specifying a transport type.
Core Elements - Required
| Element | Description |
|---|---|
| EndDateLocal | The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss |
| StartCity | The starting address of the booking. |
| StartCityCode | The IATA airport code for the starting city of the booking. |
| StartDateLocal | The starting date of travel for this segment, in the local time of to the starting point. Format: YYYY-MM-DDThh:mm:ss |
Core Elements - Optional
| Element | Description |
|---|---|
| CancellationNumber | The cancellation number from the vendor. This field should be set when you cancel a segment. |
| ConfirmationNumber | The confirmation number from the vendor. |
| Currency | The 3-letter ISO 4217 currency code for the booking. |
| DailyRate | Average per day rate for the booking. If the rate varies over the duration, it can be specified using the charges model. |
| DateCancelledUtc | The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| DateCreatedUtc | The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| DateModifiedUtc | The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| EndAddress | The ending address of the booking. |
| EndAddress2 | The ending address of the booking. |
| EndCity | The ending address of the booking. |
| EndCityCode | The IATA airport code for the ending city of the booking. |
| EndCountry | The ending address of the booking. |
| EndDateUtc | The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| EndLatitude | The latitude for the ending location of the booking. |
| EndLocation | The ending location of the booking. |
| EndLongitude | The longitude of the ending point of the booking. |
| EndPostalCode | The ending address of the booking. |
| EndState | The ending address of the booking. |
| TransportMode | The transport mode of the booking. |
| Notes | Additional information about the booking. |
| NumPersons | The number of persons booked for the trip. |
| PhoneNumber | The parking phone number. |
| SpecialInstructions | The instructions for the booking. Max Length: 256 |
| StartAddress | The starting address of the booking. |
| StartAddress2 | The starting address of the booking. |
| StartCity | The starting address of the booking. |
| StartCityCode | The IATA airport code for the starting city of the booking. |
| StartCountry | The starting address of the booking. |
| StartDateUtc | The starting date of travel for this segment, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| StartLatitude | The latitude of the starting location of the booking. |
| StartLongitude | The longitude of the starting location of the booking. |
| StartPostalCode | The starting address of the booking. Maximum length: 24 |
| StartState | The starting address of the booking. Maximum length: 50 |
| Status | The booking status. |
| TimeZone | The time zone of the booking. Format: One of the supported Olson or Windows Time Zones. |
| TotalRate | The total rate amount of the booking. |
| Vendor | The two letter GDS vendor code. |
| VendorName | The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary. |
| Charges | The charges for this booking. Refer to the Charges Child Elements table. |
| Seats | The seats for the booking. This parent element contains an TravelSeat element for each included seat. The TravelSeat element contains the following child elements: |
TravelSeat Elements
| Element | Description |
|---|---|
| PassengerRph | The passenger assigned to the seat. |
| SeatNumber | The number of the seat. |
Charges Child Elements
Core Elements - Required
Percent - The Percent of Fixed Charges
This parent element contains the following child elements:
| Element | Description |
|---|---|
| Amount | The total amount for the rate for the booking. |
| Currency | The 3-letter ISO 4217 currency code for the total amount. |
| Description | The description for the rate. |
| IsPaid | Whether the rate has been paid. Format: true/false. |
| IsPrimary | Indicates whether the charge is the Primary or Main rate. For example, if one of the rates is the actual rate and the rest are penalties, the actual rate should be set as IsPrimary. Only one charge in a set should be primary. Format: true/false. |
| SemanticsCode | Indicates the charge category for the line item. |
| SemanticsVendorType | The vendor type: H=Hotel, C=Car, A=Air, G=Ground, R=Rail |
| StartDateLocal | The start date of the booking, in the user's local time. Format: YYYY-MM-DDThh:mm:ss |
| Vendor | The vendor for the booking charge. |
| VendorChargeCode | The vendor's code for the charge |
Fixed - The Fixed Charges
This parent element contains the following child elements:
| Element | Description |
|---|---|
| Currency | The 3-letter ISO 4217 currency code for the total amount. |
| Description | The description for the fixed amount. |
| IsPaid | Whether the fixed amount has been paid. Format: true/false. |
| IsPrimary | Whether the fixed amount is primary. Format: true/false. |
| SemanticsCode | Indicates the charge category for the line item. Refer to the Semantics and Vendor Codes document for more information. |
| SemanticsVendorType | The vendor type: H=Hotel, C=Car, A=Air, G=Ground, R=Rail |
| StartDateLocal | The start date of the booking, in the user's local time. Format: YYYY-MM-DDThh:mm:ss |
| Vendor | The vendor applying the booking charge. |
| VendorChargeCode | The vendor's code for the charge. |
Rate - The Rate for the Booking
This parent element contains the following child elements:
| Element | Description |
|---|---|
| Amount | The total amount for the rate for the booking. |
| Currency | The 3-letter ISO 4217 currency code for the total amount. |
| Description | The description for the rate. |
| IsPaid | Whether the rate has been paid. Format: true/false. |
| IsPrimary | Whether the rate is primary. Format: true/false. |
| NumUnits | The number of units expected for the charge. For instance, 3 days |
| PerUnit | The unit of measure for the charge. Values represent rates like per DAY, WEEK, or MONTH |
| SemanticsCode | Indicates the charge category for the line item. Refer to the Semantics and Vendor Codes document for more information. |
| SemanticsVendorType | The vendor type: H=Hotel, C=Car, A=Air, G=Ground, R=Rail |
| StartDateLocal | The start date of the booking, in the user's local time. Format: YYYY-MM-DDThh:mm:ss |
| Vendor | The vendor for the booking charge. |
| VendorChargeCode | The vendor's code for the charge. |
RateWithAllowance - The Rate for the Booking, Including any Travel Allowances
This parent element contains the following child elements:
| Element | Description |
|---|---|
| AllowanceAmount | The cost of overage fees when the allowance is exceeded. For example, if the allowance is 5000 miles, the cost could be $0.02 per mile. The overage must be in the same currency as the basic rate. |
| AllowanceIsUnlimited | Whether the allowance is unlimited. Format: true/false. |
| AllowanceNumUnits | The number of units for the allowance associated with the charge. For example, 5000 miles. |
| AllowanceUnit | The unit of measure for the allowance associated with the charge. For example, a car weekly rate might allow 5000 miles included in the rate. |
| Amount | The total amount for the rate for the booking. |
| Currency | The 3-letter ISO 4217 currency code for the total amount. |
| Description | The description for the rate. |
| IsPaid | Whether the rate has been paid. Format: true/false. |
| IsPrimary | Indicates whether the charge is the Primary or Main rate. For example, if one of the rates is the actual rate and the rest are penalties, the actual rate should be set as IsPrimary. Only one charge in a set should be primary. Format: true/false. |
| NumUnits | The number of units expected for the charge. For instance, 3 days. |
| PerUnit | The unit of measure for the charge. Values represent rates like per DAY, WEEK, or MONTH |
| SemanticsCode | Indicates the charge category for the line item. Refer to the Semantics and Vendor Codes document for more information. |
| SemanticsVendorType | The vendor type: H=Hotel, C=Car, A=Air, G=Ground, R=Rail |
| StartDateLocal | The start date of the booking, in the user's local time. Format: YYYY-MM-DDThh:mm:ss |
| Vendor | The vendor for the booking charge. |
| VendorChargeCode | The vendor's code for the charge. |
Time Zone Formats
Olson Time Zones
| Africa/Cairo | Africa/Casablanca | Africa/Harare | Africa/Luanda |
| Africa/Nairobi | Africa/Windhoek | America/Anchorage | America/Argentina/Buenos_Aires |
| America/Asuncion | America/Bahia | America/Bogota | America/Buenos_Aires |
| America/Caracas | America/Chicago | America/Chihuahua | America/Denver |
| America/Godthab | America/Guyana | America/Halifax | America/Indianapolis |
| America/Los_Angeles | America/Manaus | America/Mexico_City | America/Montevideo |
| America/New_York | America/Phoenix | America/Regina | America/Santiago |
| America/Sao_Paulo | America/St_Johns | America/Swift_Current | America/Tijuana |
| Asia/Almaty | Asia/Amman | Asia/Baghdad | Asia/Baku |
| Asia/Bangkok | Asia/Beirut | Asia/Calcutta | Asia/Colombo |
| Asia/Damascus | Asia/Dhaka | Asia/Irkutsk | Asia/Jerusalem |
| Asia/Kabul | Asia/Kamchatka | Asia/Karachi | Asia/Karachi |
| Asia/Katmandu | Asia/Krasnoyarsk | Asia/Magadan | Asia/Muscat |
| Asia/Novosibirsk | Asia/Rangoon | Asia/Riyadh | Asia/Seoul |
| Asia/Shanghai | Asia/Singapore | Asia/Taipei | Asia/Tbilisi |
| Asia/Tehran | Asia/Tokyo | Asia/Ulaanbaatar | Asia/Vladivostok |
| Asia/Yakutsk | Asia/Yekaterinburg | Asia/Yerevan | Atlantic/Azores |
| Atlantic/Cape_Verde | Atlantic/South_Georgia | Australia/Adelaide | Australia/Brisbane |
| Australia/Darwin | Australia/Hobart | Australia/Perth | Australia/Sydney |
| Etc/GMT+12 | Etc/GMT-11 | Etc/GMT-2 | Europe/Athens |
| Europe/Berlin | Europe/Helsinki | Europe/Istanbul | Europe/Kaliningrad |
| Europe/London | Europe/Minsk | Europe/Moscow | Europe/Paris |
| Europe/Prague | Europe/Sarajevo | GMT | GMT-1200 |
| Indian/Mauritius | Pacific/Apia | Pacific/Auckland | Pacific/Fiji |
| Pacific/Guadalcanal | Pacific/Guam | Pacific/Honolulu | Pacific/Tongatapu |
| UTC |
Windows Time Zones
| Africa/Cairo | Africa/Casablanca | Africa/Harare | Africa/Luanda |
| Africa/Nairobi | Africa/Windhoek | America/Anchorage | America/Argentina/Buenos_Aires |
| America/Asuncion | America/Bahia | America/Bogota | America/Buenos_Aires |
| America/Caracas | America/Chicago | America/Chihuahua | America/Denver |
| America/Godthab | America/Guyana | America/Halifax | America/Indianapolis |
| America/Los_Angeles | America/Manaus | America/Mexico_City | America/Montevideo |
| America/New_York | America/Phoenix | America/Regina | America/Santiago |
| America/Sao_Paulo | America/St_Johns | America/Swift_Current | America/Tijuana |
| Asia/Almaty | Asia/Amman | Asia/Baghdad | Asia/Baku |
| Asia/Bangkok | Asia/Beirut | Asia/Calcutta | Asia/Colombo |
| Asia/Damascus | Asia/Dhaka | Asia/Irkutsk | Asia/Jerusalem |
| Asia/Kabul | Asia/Kamchatka | Asia/Karachi | Asia/Karachi |
| Asia/Katmandu | Asia/Krasnoyarsk | Asia/Magadan | Asia/Muscat |
| Asia/Novosibirsk | Asia/Rangoon | Asia/Riyadh | Asia/Seoul |
| Asia/Shanghai | Asia/Singapore | Asia/Taipei | Asia/Tbilisi |
| Asia/Tehran | Asia/Tokyo | Asia/Ulaanbaatar | Asia/Vladivostok |
| Asia/Yakutsk | Asia/Yekaterinburg | Asia/Yerevan | Atlantic/Azores |
| Atlantic/Cape_Verde | Atlantic/South_Georgia | Australia/Adelaide | Australia/Brisbane |
| Australia/Darwin | Australia/Hobart | Australia/Perth | Australia/Sydney |
| Etc/GMT+12 | Etc/GMT-11 | Etc/GMT-2 | Europe/Athens |
| Europe/Berlin | Europe/Helsinki | Europe/Istanbul | Europe/Kaliningrad |
| Europe/London | Europe/Minsk | Europe/Moscow | Europe/Paris |
| Europe/Prague | Europe/Sarajevo | GMT | GMT-1200 |
| Indian/Mauritius | Pacific/Apia | Pacific/Auckland | Pacific/Fiji |
| Pacific/Guadalcanal | Pacific/Guam | Pacific/Honolulu | Pacific/Tongatapu |
| UTC |
Itinerary Service
- Overview
- Version
- Resources
- Concepts
- Who Can Use This Web Service?
- Authentication and Authorization
- Configuration
- FAQs
- Best Practices
- Reference
Overview
The Itinerary API can be used to programmatically access travel data such as trips and bookings in Concur Travel. Concur Travel uses this data to match and consolidate bookings it receives from disparate sources and put these into consolidated travelers’ itineraries, providing travelers a convenient way to view their trips in a single itinerary view. Travelers can view their itineraries through mobile applications or other services.
Version
Version 1.0
Resources
Concepts
Itineraries and Trips
The terms itinerary and trip are synonyms. Trip is the name used for the SAP Concur web service resource that represents an itinerary.
Itinerary, Booking Record, and Segment
- An itinerary is the container for all bookings in a trip. An itinerary can have more than one booking.
- A booking record is the container for all segments booked from a source with the same unique identifier (record locator or confirmation number). A single booking can have multiple segments.
- A segment includes details about the travel booking.
Who Can Use This Web Service?
TripLink suppliers, travel management companies (TMCs), and SAP Concur clients and third-party developers can use the Itinerary API. The level of access to the data in the Concur Travel system depends on who is accessing it and the SAP Concur products that have been purchased.
Travel Management Companies
- Can view and post bookings for any travel type.
- Send new reservations that users create on the supplier's site to SAP Concur.
- Send a notice of trip cancellations to SAP Concur.
- Get a list of current trips for a user from SAP Concur.
- Get the full details of user trips from SAP Concur.
- Can view the full set of fields for their customers' itineraries because TMCs have an existing relationship with their customers.
- Can send proposed itineraries when the Agency Proposal feature of Concur Request is active.
- Can cancel bookings on behalf of a user.
TripLink Travel Suppliers
- Can post bookings for their travel type.
- Get limited itinerary details.
- Get the full details of the bookings that they own, but see a limited set of fields and data for other bookings.
- Modify bookings.
- Cancel bookings for their travel type.
SAP Concur Clients and Third-Party Developers
- Get trip information for SAP Concur users. SAP Concur clients who purchase Web Services have access to their own trip data, while third party developers have access to the SAP Concur trip data of the clients who authorize them.
- Third-party partner developers must determine which configurations are required for their solution prior to the review process.
SAP Concur products are highly configurable, and not all clients will have access to all features. Some itinerary data may have come from Sabre. SAP Concur encourages you to speak to Sabre about becoming a Sabre Authorized Developer.
Authentication and Authorization
The Itinerary API uses OAuth 2.0 for authenticating users and authorizing access to travel data.
Authorization for TMCs
TMCs can request or send travel bookings in two ways:
- By using an OAuth token for the user the travel booking belongs to. This token allows access to the user's data.
- By using an OAuth token for a user with an administrative role at the company, which allows access to company-wide information. The user who authenticates during this OAuth process must have an SAP Concur account with one of the following user roles: Web Services Administrator for Professional, or Can Administer for Standard.
Authorization for TripLink Suppliers
The travel supplier can request or send travel bookings by using an OAuth token for the user the travel booking belongs to, generated with the user's involvement.
Configuration
- If you are a TMC, third-party developer, or a TripLink supplier who would like to start using this web service, please visit: [http://www.concur.com/en-us/connect-platform/suppliers][3] or contact the SAP Partner Enablement Team.
- SAP Concur products are highly configurable, and not all SAP Concur clients will have access to all features.
- Partner developers must determine which configurations are required for their solution prior to the review process.
FAQs
When Do I Send Trips Versus Bookings?
- TMCs, OTA, or partners that own or manage the entire trip on behalf of the traveler should send trips.
- Travel suppliers such as hotels, car vendors or airlines that own only parts of the trips should send bookings.
- Posted bookings are merged with any existing trips if their dates overlap.
- Posted trips are not merged even if a trip already exists with overlapping dates.
Can Other TripLink Suppliers See all the Booking Details of My Bookings?
The Itinerary API returns the full booking details to the supplier who will provide the booked service. Suppliers that are not the service provider will receive a subset of the possible fields. These vary by the type of booking relative to the type of supplier. For example, Air booking suppliers that are not the supplier will not see the following fields:
- Vendor
- FlightNumber
- StartDateLocal
- StartDateUtc
How Can We Save Additional Charges for Hotel and Car Segments? What Types of Charges Are Supported?
The Charges element under Car and Hotel segments allow you to save additional charges using Semantics Codes. Refer to the Semantics and Vendor Codes sections under Reference for more information.
What Vendor Codes Can I Use When Sending Hotel and Car Segments?
Refer to the Semantics and Vendor Codes sections for the full list.
Can I View a Trip Posted Through the Itinerary API in the SAP Concur UI?
Yes. The user who owns the trip will see the trip on their home page. If the trip is in the future, it will show under the upcoming trip list. Trips that are ready to expense will show in the expense report list.
When Can a Trip Be Expensed?
Trips can be expensed after the trip is over under the following conditions:
- The trip has a Car, Hotel, or Ride segment.
- The trip has an Air segment with a ticket and the ticket has at least one valid ticket coupon, meaning the coupon is in one of the following statuses:
- OPEN
- USED
- PRTD
- StartDateUtc
Air segments can be expensed as soon as they have a ticket with a valid coupon, if the company uses the PreExpenseAir option.
Why is My New Booking Not Showing in the UI?
The request returned successfully with HTTP status - 200 OK. Posted bookings are automatically merged with any existing trip with overlapping dates. Most likely, a trip exists with the same dates and the booking has been added to it.
Will Posted Bookings Be Overwritten by Emailed or TripIt Trips?
No.
Will Posted Bookings Merge with Existing Cliqbook or TripIt Trips?
Yes.
Will Posted Trips Merge with Existing Trips?
No.
Best Practices
- When extracting past data:
- Extract a month of trip summaries to gauge volume. If hundreds are returned, then adjust extraction to weekly.
- Do not extract more than a year of data at any given time regardless of the volume. For longer look backs, extract six month segments maximum at a time.
- Do not multi-thread requests to retrieve multiple pages of data. Concurrent requests will impact your application’s performance.
- This API will only return itineraries that have been sent to Concur Travel; this includes travel booked within Concur Travel, TripIt, on TripLink supplier sites, plans emailed to Concur, and most bookings from your travel agency.
- Some customers may have multiple booking options, which may mean not all employee trips are available via this API. A good rule of thumb: if the traveler sees the itinerary in their “trips” list, then you can retrieve it from this API.
- Because the data comes from many sources, data across itineraries may not be consistent. It’s recommended that you only consume the relevant segments and data (for example, air only or air + hotel) for your application’s function.
- Itineraries change frequently. Changes do not necessarily indicate that the traveler modified their trip. You should address relevant changes only. This may mean comparing what your application considers relevant (for example, trip dates) across updated itineraries. In addition:
- If your application works with upcoming or in progress trips, be aware that you must evaluate the individual segments to determine whether it is a material change for your application.
- If your app is consuming itineraries before the trip occurs, cancellations should be taken into account. To incorporate cancelled trips, set the
includeCancelledtripsflag to “true” and leverage the trip status field to determine the application action.
- Your app should log key identifiers in addition to the
tripID. It is recommended that “client locator” and user UUID be tracked so you can troubleshoot issues and match to data that customers have available. - Many customers will opt-in to your integration for only a subset of their regions. It is recommended that you provide options, leveraging the user’s country in the travel profile, to determine which itineraries to extract.
- There are three different booking modes, all of which should be considered when building your application. Note that some clients additionally allow individuals to book for multiple passengers at a time.
- An individual booking for themselves.
- An individual booking on behalf of another user (profiled user).
- An individual booking for a guest (non-profiled user).
Reference
The Itinerary Reference documentation includes the following reference information that can be used in conjunction with the Trip Resource API and Booking Resource API documentation. It includes the following reference topics:
- Itinerary Data Model
- Car Vendor Codes
- Hotel Vendor Codes
- Ride Vendor Codes
- Semantics Codes
- Time Zone Formats
Itinerary Data Model
The Itinerary data model defines data elements that are returned or sent when getting, creating, updating, or deleting trips and bookings with the /api/travel/trip/v1.1 and /api/travel/booking/v1.1 resources respectively.
Trips include all bookings in an itinerary whereas a booking includes only a specific segment of an itinerary. It includes the following elements:
- Root Elements
- Booking Elements
- AirfareQuotes Elements
- Passengers Elements
- AirlineTickets Elements
- Fixed Elements
- AirBooking Elements
- CarBooking Elements
- Hotel Booking Elements
- Dining Booking Elements
- Ride Booking Elements
- Rail Booking Elements
- Parking Booking Elements
- Travel Booking Elements
Root Elements
| Element Name | Data Type | TripLink | Description |
|---|---|---|---|
| id | String | Y | The unique identifier for the trip URI with encrypted ID. |
| ItineraryInfo | Y | Parent element with the information about an itinerary for the specified user. | |
| TripId | String | Y | Encrypted trip identifier value. |
| ItinLocator | String | Y | This element is obsolete and is supported only for backward compatibility. |
| BookedVia | String | The booking method for the trip. | |
| BookedByFirstName | String | Y | The first name of the person who booked the trip. |
| BookedByLastName | String | Y | The last name of the person who booked the trip. |
| HasOpenBookingPassive | String | ||
| CancelComments | String | Y | The comments provided if the itinerary is cancelled. Maximum length: 256 characters. |
| ClientLocator | String | ||
| TripLinkLocator | String | ||
| Comments | String | Y | (Description here). Maximum length 512 characters. |
| DateBookedLocal | DateTime | Y | The date the trip was booked, in the local time of the booking location. Format: YYYY-MM-DDThh:mm:ss |
| DateCreatedUtc | DateTime | Y | The date that this trip was created, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| DateModifiedUtc | DateTime | Y | The date when this trip was last modified in UTC format. Format: YYYY-MM-DDThh:mm:ss. |
| Description | String | Y | The description for this trip. Maximum length 512 characters. |
| EndDateLocal | DateTime | Y | The end date of the trip in the ending location’s timezone. Format: YYYY-MM-DDThh:mm:ss. |
| EndDateUtc | DateTime | Y | The end date of the trip, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| TravelRequestId | String | ||
| IsPersonal | Boolean | Y | Indicates whether this trip is for business or for leisure. Format: Business, Leisure |
| ProjectName | String | The name of the project assiciated with this trip. Maximum length 255 characters. | |
| StartDateLocal | DateTime | Y | The start date of the trip in the starting location’s timezone. Format: YYYY-MM-DDThh:mm:ss. |
| StartDateUtc | DateTime | Y | The date when this trip started in UTC format. Format: YYYY-MM-DDThh:mm:ss. |
| TripName | String | Y | Name of the trip. Maximum length 255 characters. |
| TripStatus | unsignedByte | Y | The status of the trip. This element only appears if the includeCanceledTrips query parameter is used in the request. |
| UserLoginId | Y | The user's login to SAP Concur. This element appears only when the OAuth token is associated with a SAP Concur account with one of these roles: Web Services Administrator for Professional or Can Administer for Standard. | |
| Bookings | Array | Y | An array of bookings that contains a Booking child element for each included booking. |
| Custom Attributes | Array | ||
| RuleViolations | Array | N | The list of rule violations associated with the itinerary. This parent element contains a RuleViolation child element for each associated rule violation. |
Booking Elements
The Bookings parent element contains a Booking child element for each included booking. TripLink suppliers have access only to a subset of the Booking elements. The TripLink column indicates with a Y if a specific element is available for a TripLink supplier. Each booking element contains the following child elements:
| Element | Data Type | TripLink | Description |
|---|---|---|---|
| BookingOwner | String | Y | Specifies the tool that supplied the booking to Concur Travel. The possible values are: ConcurTravel, OpenBookingEmail, AmadeusETravel, ConcurConnectAPI, OpenBookingSupplier and TripIt |
| BookingSource | String | Y | For TMCs: The name of the booking source for this booking. A booking source is a textual name the system uses to track where a booking took place. For TripLink suppliers: The name of the booking source for this booking. A booking source is a textual name the system uses to track where a booking took place. This could be a GDS, OTA, Vendor Code for Supplier website or Supplier Direct Connect API |
| Source | Y | This element is obsolete and is supported only for backward compatibility. | |
| DateBookedLocal | DateTime | Y | The date the booking was created, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss |
| DateCreatedUtc | DateTime | Y | The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| DateModifiedUtc | DateTime | Y | The date the booking was last modified, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| FareExpiresEmailDatetimeUtc | DateTime | ||
| FormOfPaymentName | String | The name of the form of payment for the booking. | |
| FormOfPaymentType | String | The type of the form of payment. | |
| LastTicketDateUtc | DateTime | ||
| PassengerCount | Int | The total count of passengers for the booking. | |
| RecordLocator | String | Y | The unique identifier for the booking |
| RetrievedDateUtc | |||
| TicketMailingAddress | The mailing address for the booked ticket, if available. | ||
| TicketPickupLocation | The pickup location for the booked ticket, if available | ||
| TicketPickupNumber | The confirmation number to pick up the booked ticket, if available. | ||
| CreditCardType | String | The type of credit card (for example, Visa/Mastercard/etc.). | |
| CreditCardLastFour | String | The last four digits of credit card number. | |
| AirfareQuotes | Array | List of stored airfare quotes for this booking. For more information, see the AirFareQuotes Elements table. | |
| ItinSourceName | String | The itinerary source. Format: TravelSupplier | |
| AirlineTickets | Array | List of airline tickets for this booking. For more information, see the AirLine Tickets Elements table. | |
| Charges | Array | The charges for this booking. For more information, see the Charges Elements table later on this page. | |
| MiscChargeOrders | Array | An array of miscellaneous charge orders for this booking. This parent element has a MiscellaneousChargeOrders child element for each miscellaneous charge order associated with this booking. For information about the child elements, see the MiscellaneousChargeOrders Elements table later on this page. | |
| Passengers | Array | Y | This parent element contains a Passenger child element for each booked passenger. See the Passengers Elements table for more information about the child elements. |
| PassPrograms | List of Pass Programs for this booking. This parent element has a PassProgram child element for each pass program associated with the booking. For information about the child elements, see the PassProgram Elements table later on this page. | ||
| PhoneNumbers | List of Phone numbers associated with this booking. This parent element has a PhoneNumberData child element for each phone number associated with the booking. For information about the child elements, see the PhoneNumberData Elements table later on this page. | ||
| RailPayments | Array | List of Rail payments associated with rail segments in this booking. For information about the child elements in the array, see the RailPayments Elements table later on this page. | |
| Segments | Y | List of Segments in this booking. This parent element contains one or more Air, Car, Hotel, Dining, Ride, Rail, Parking, or Travel parent elements for the booking. The segments are described in the tables below, see Air Booking Elements, Car Booking Elements, Hotel Booking Elements, Dining Booking Elements, Ride Booking Elements, Parking Booking Elements, and Travel Booking Elements. | |
| Delivery | String | The method this booking was delivered. | |
| WaitListSegments | The segments that the traveler is waitlisted for this booking. | ||
| Warnings | The warnings associated with the booking. | ||
| WebAddresses | List of web addresses such as emails and pickup URLs associated with this booking. |
MiscellaneousChargeOrder Elements
| Element Name | Data Type | TripLink | Description |
|---|---|---|---|
| DateCreatedUtc | dateTime | The date the charge order was created, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| DateModifiedUtc | dateTime | The date the charge order was last modified, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| IssueDate | dateTime | The date the charge order was issued. Format: YYYY-MM-DDThh:mm:ss | |
| PlatingCarrierNumericCode | string | Part of the ticket number that indicates the airline code. This is a three digit number. For example: 001=American, 005=Continental, 006=Delta, 012=Northwest | |
| PlatingControlNumber | string | Part of the ticket number that indicates the ticket control number. Format: Ten digit number. | |
| TotalAmount | decimal | The total amount of charge orders for the ticket. | |
| TotalAmountCurrency | string | The 3-letter ISO 4217 currency code for the total charge order amount. |
PassProgram Elements
| Element Name | Data Type | TripLink | Description |
|---|---|---|---|
| Amount | decimal | The program amount. | |
| Name | string | The program name. | |
| Type | string | The program type. | |
| UserFirstName | string | The first name of the passenger. | |
| UserLastName | string | The last name of the passenger. |
PhoneNumberData Elements
| Element Name | Data Type | TripLink | Description |
|---|---|---|---|
| PassengerRPH | integer | Indicates the passenger to whom this phone number belongs. | |
| PhoneNumber | string | The passenger's phone number. | |
| Type | string | The type of phone number. | |
| Description | string | The description for the phone number. |
RailPayments Elements
| Element Name | Data Type | TripLink | Description |
|---|---|---|---|
| RailAdjustment | Type | The amount adjusted for a rail booking. For information about the RailAdjustment child elements, see the RailAdjustment Elements table later on this page. | |
| RailPayment | Type | The payment information for a rail booking. For information about the RailPayment child elements, see the RailPayment Elements table later on this page. |
RailAdjustment Elements
| Element Name | Data Type | TripLink | Description |
|---|---|---|---|
| AdjustmentDateTime | dateTime | ||
| AdjustmentDateTimeUTC | dateTime | ||
| AdjustmentType | string | ||
| DateCreatedUtc | dateTime | ||
| DateModifiedUtc | dateTime | ||
| TicketDocumentIdentifier | string | ||
| TotalAdjustment | decimal | ||
| TotalAdjustmentCurrency | string | ||
| Taxes | Array | This parent element contains a Tax child element for each rail adjustment tax. For more information, see the Tax Elements table later on this page. |
RailPayment Elements
| Element Name | Data Type | TripLink | Description |
|---|---|---|---|
| BaseFare | decimal | The base fare of the booking quote. | |
| BaseFareCurrency | string | The 3-letter ISO 4217 currency code for the total fare. | |
| DateCreatedUtc | dateTime | The date the quote was created, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| DateModifiedUtc | dateTime | The date the quote was last modified, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| IssueByDate | dateTime | The date the quote must be issued by. Format: YYYY-MM-DDThh:mm:ss | |
| IssueDateTime | dateTime | ||
| IssueDateTimeUTC | dateTime | ||
| TicketDocumentIdentifier | string | ||
| TicketType | string | ||
| TotalFare | decimal | The total price of the booking. | |
| TotalFareCurrency | string | The 3-letter ISO 4217 currency code for the total fare. | |
| RailCharges | array | The charges applied by the airline. This parent element contains a Fixed and a Tax child element for each fixed charge and tax from the airline. See the Fixed Elements table and the Tax Elements table. |
AirfareQuotes Elements
The AirfareQuotes parent element is an array that contains a Quote child element that contains the following child elements.
| Element Name | Data Type | TripLink | Description |
|---|---|---|---|
| BaseFare | Decimal | ||
| BaseFareCurrency | String | ||
| BaseFareNuc | Decimal | ||
| BaseFareNucCurrency | String | ||
| DateCreatedUtc | DateTime | ||
| DateModifiedUtc | DateTime | ||
| Endorsements | String | ||
| IssueByDate | DateTime | ||
| TotalFare | Decimal | ||
| TotalFareCurrency | String | ||
| AirlineCharges | Array | This parent element contains a Fixed and a Percent child element for each fixed charge and percent of fixed charge associated with this airfare quote. For information about these child elements, see the Fixed Elements table and the Percent Elements table later on this page. |
Passengers Elements
The passenger parent element is the Passengers Element in Booking Elements. This parent element contains a Passenger child element for each booked passenger.
| Element Name | Data Type | Required/Optional | TripLink | Description |
|---|---|---|---|---|
| NameFirst | String | required | Y | The first name of the passenger. |
| NameLast | String | required | Y | The last name of the passenger. |
| NameMiddle | String | optional | Y | The middle name of the passenger. |
| NamePrefix | String | optional | Y | The name prefix of the passenger. |
| NameRemark | String | optional | Y | Additional details about the passenger's name. |
| NameSuffix | String | optional | Y | The name suffix of the passenger. |
| NameTitle | String | optional | Y | The title of the passenger. |
| TextName | String | optional | Y | The user's full name as entered in the booking tool if different from the name in the database. |
| FrequentTravelerProgram | String | optional | Y | Passenger's loyalty programs |
AirlineTickets Elements
The AirlineTickets parent element is an array that contains the following child elements.
| Element Name | Data Type | TripLink | Description |
|---|---|---|---|
| AirlineAdjustmentType | Type | Any adjustment made to the booking. For information about the child elements of AirlineAdjustmentType, see the AirlineAdjustmentType Elements table later on this page. | |
| ManualAirlineTicket | Type | The manual airline ticket for the booking. For information about the child elements of ManualAirlineTicket, see the ManualAirlineTicket Elements table later on this page. | |
| AirlineTicket | Type | The airline ticket for the booking. For information about the child elements of AirlineTicket, see the AirlineTicket Elements table later on this page. |
AirlineAdjustmentType Elements
| Element Name | Data Type | TripLink | Description |
|---|---|---|---|
| AddCollectAmount | decimal | ||
| AdjustmentDateTime | dateTime | ||
| AdjustmentDateTimeUTC | dateTime | ||
| AdjustmentType | String | ||
| DateCreatedUtc | dateTime | ||
| DateModifiedUtc | dateTime | ||
| PassengerName | string | ||
| PlatingCarrierNumericCode | string | ||
| PlatingControlNumber | string | ||
| RecordLocator | string | ||
| TotalAdjustment | decimal | ||
| TotalAdjustmentCurrency | string | ||
| Taxes | Array |
ManualAirlineTicket Elements
| Element Name | Data Type | TripLink | Description |
|---|---|---|---|
| BaseFare | decimal | ||
| BaseFareCurrency | string | ||
| DateCreatedUtc | dateTime | ||
| DateModifiedUtc | dateTime | ||
| TotalFareTotalFareCurrency | decimal | ||
| AirlineCharges | array | The charges applied by the airline. This parent element contains a Fixed and a Tax child element for each fixed charge and tax from the airline. For information about these child elements, see the Fixed Elements table and the Tax Elements table later on this page. |
AirlineTicket Elements
| Element Name | Data Type | TripLink | Description |
|---|---|---|---|
| AddCollectAmount | decimal | ||
| AccountingLine | string | ||
| BaseFare | decimal | ||
| BaseFareCurrency | string | ||
| BaseFareNuc | decimal | ||
| BaseFareNucCurrency | string | ||
| ComparisonFare | decimal | ||
| ComparisonFareCurrency | string | ||
| DateCreatedUtc | dateTime | ||
| DateModifiedUtc | dateTime | ||
| Endorsements | string | ||
| InvoiceNumber | string | ||
| IssueDateTime | dateTime | ||
| IssueDateTimeUTC | dateTime | ||
| IssuingIataAgencyNumber | integer | ||
| IssuingPseudoCity | string | ||
| LinearFareConstructor | string | ||
| MasterTicketNumber | string | ||
| NameReference | string | ||
| PassengerName | string | ||
| PlatingCarrierNumericCode | string | ||
| PlatingControlNumber | string | ||
| ProgramCarrierCode | string | ||
| ProgramMembershipNumber | string | ||
| RecordLocator string | string | ||
| SabreDkNumber string | string | ||
| Ticketless | boolean | ||
| TicketType | string | ||
| TotalFare | decimal | ||
| TotalFareCurrency | string | ||
| TourIdentifier | string | ||
| AirlineCharges | array | A list of airline charges for this ticket. This parent element contains a Fixed child element for each fixed charge from the airline. For information about these child elements, see the Fixed Elements table later on this page. | |
| AirlineTicketCoupons | array | A list of coupons for this ticket. This parent element has an AirlineTicketCoupon child element for each coupon associated with this airline ticket. For information about these child elements, see the AirlineTicketCoupon Elements table later on this page. | |
| AirlineTicketExchanges | array | A list of exchanges for this ticket. This parent element has an AirlineTicketExchange child element for each exchange associated with this airline ticket. For information about these child elements, see the AirlineTicketExchange Elements table later on this page. | |
| AirlineTicketFareBreakups | array | A list of fare breakups for this ticket. This parent element has an AirlineTicketFareBreakup child element for each fare breakup associated with this airline ticket. For information about these child elements, see the AirlineTicketFareBreakup Elements table later on this page. |
AirlineTicketCoupons Elements
| Element Name | Data Type | TripLink | Description |
|---|---|---|---|
| ClassOfService | string | ||
| CouponNumber | unsignedByte | ||
| CouponStatus | string | ||
| EndCityCode | string | ||
| FlightNumber | string | ||
| NotValidAfterDate | dateTime | ||
| NotValidBeforeDate | dateTime | ||
| RateCode | string | ||
| StartCityCode | sring | ||
| StartDateLocal | dateTime | ||
| Status | string | ||
| TicketDesignator | string | ||
| Vendor | string |
AirlineTicketExchanges Elements
| Element Name | Data Type | TripLink | Description |
|---|---|---|---|
| Amount | decimal | ||
| AppliedSegment1 | unsignedByte | ||
| AppliedSegment10 | unsignedByte | ||
| AppliedSegment2 | unsignedByte | ||
| AppliedSegment3 | unsignedByte | ||
| AppliedSegment4 | unsignedByte | ||
| AppliedSegment5 | unsignedByte | ||
| AppliedSegment6 | unsignedByte | ||
| AppliedSegment7 | unsignedByte | ||
| AppliedSegment8 | unsignedByte | ||
| AppliedSegment9 | unsignedByte | ||
| Currency | string | ||
| OldRecordLocator | string | ||
| DateModifiedUtc | dateTime | ||
| PlatingCarrierNumericCode | string | ||
| PlatingControlNumber | string |
AirlineTicketFareBreakups Elements
| Element Name | Data Type | TripLink | Description |
|---|---|---|---|
| BaseFare | decimal | ||
| BaseFareCurrency | sring | ||
| DateCreatedUtc | dateTime | ||
| DateModifiedUtc | dateTime | ||
| IssueByDate | dateTime | ||
| IssueDateTime | dateTime | ||
| IssueDateTimeUTC | dateTime | ||
| TicketDocumentIdentifier | string | ||
| TicketType | string | ||
| TotalFare | decimal | ||
| TotalFareCurrency | string | ||
| Taxes | array | The charges applied by the airline. This parent element contains a Fixed and a Tax child element for each fixed charge and tax from the airline. For more information, see the Fixed Elements table and the Tax Elements table later on this page. |
Fixed Elements
The Fixed element contains the following child elements.
| Element Name | Data Type | TripLink | Description |
|---|---|---|---|
| Amount | Decimal | The total amount for the rate for the booking. | |
| Currency | String | The 3-letter ISO 4217 currency code for the total amount. | |
| Description | String | The description for the rate. | |
| IsPaid | Boolean | Whether the rate has been paid. Format: true/false. | |
| IsPrimary | Boolean | Indicates whether the charge is the Primary or Main rate. For example, if one of the rates is the actual rate and the rest are penalties, the actual rate should be set as IsPrimary. Only one charge in a set should be primary. Format: true/false. | |
| SemanticsCode | String | Indicates the charge category for the line item. Refer to the Semantics Codes table for more information. | |
| SemanticsVendorType | String | The vendor type: H=Hotel, C=Car, A=Air, G=Ground, R=Rail | |
| StartDateLocal | DateTime | The start date of the booking, in the user's local time. Format: YYYY-MM-DDThh:mm:ss | |
| Vendor | String | The vendor for the booking charge. | |
| VendorChargeCode | String | The vendor's code for the charge |
Tax Elements
This Tax element contains the following child elements.
| Element Name | Data Type | TripLink | Description |
|---|---|---|---|
| TaxAmount | Decimal | The amount of the tax. | |
| TaxType | String | The type of the tax. |
Percent Elements
The percent of fixed charges. This parent element contains the following child elements:
| Element | Data Type | TripLink | Description |
|---|---|---|---|
| Amount | Decimal | The total amount for the rate for the booking. | |
| Currency | string | The 3-letter ISO 4217 currency code for the total amount. | |
| Description | sring | The description for the rate. | |
| IsPaid | boolean | Whether the rate has been paid. Format: true/false. | |
| IsPrimary | boolean | Indicates whether the charge is the Primary or Main rate. For example, if one of the rates is the actual rate and the rest are penalties, the actual rate should be set as IsPrimary. Only one charge in a set should be primary. Format: true/false. | |
| SemanticsCode | string | Indicates the charge category for the line item. Refer to the Semantics Codes table for more information. | |
| SemanticsVendorType | string | The vendor type: H=Hotel, C=Car, A=Air, G=Ground, R=Rail | |
| StartDateLocal | dateTime | The start date of the booking, in the user's local time. Format: YYYY-MM-DDThh:mm:ss | |
| Vendor | string | The vendor for the booking charge. | |
| VendorChargeCode | string | The vendor's code for the charge |
CustomAttributes Elements
The CustomAttributes parent element contains a CustomAttribute child element with the following child elements.
| Element Name | Data Type | TripLink | Description |
|---|---|---|---|
| Data | String | ||
| DisplayTitle | String | ||
| DisplayValue | String | ||
| Name | String | ||
| DataType | String | ||
| DisplayOnItinerary | Boolean | ||
| ExternalId | Int |
RuleViolations Elements
The RuleViolations element contains a list of rule violations associated with the itinerary. This parent element contains a RuleViolation child element for each associated rule violation. The RuleViolation element has the following child elements:
| Element Name | Data Type | TripLink | Description |
|---|---|---|---|
| BestGdsPrice | Decimal | ||
| BestGdsVendor | String | ||
| BestInternetPrice | Decimal | ||
| BestInternetVendor | String | ||
| CompanyReasonCode | String | ||
| CompanyRuleText | String | ||
| Currency | String | ||
| DateEntered | DateTime | ||
| EndCity | String | ||
| EndDate | DateTime | ||
| NumberOfStops | Int | ||
| QuotedPrice | Decimal | ||
| RuleAction | String | ||
| RuleName | String | ||
| SegmentType | String | ||
| SelectedOtherAmount | Decimal | ||
| SelectedOtherAmountType | String | ||
| StartCity | String | ||
| StartDate | DateTime | ||
| TariffPrice | Decimal | ||
| TravelerComments | String | ||
| VendorCode | String | ||
| VendorName | String |
AirBooking Elements
The Air Booking parent element is the Air Element in the Segments Array in Booking Elements. This parent element contains an Air Booking child element for each booked flight.
| Element | Data Type | TripLink | Description |
|---|---|---|---|
| ClassOfService | string | The class of the booking. | |
| ConfirmationNumber | string | The record locator or confirmation number for the flight from the airline. | |
| EndCityCode | string | Y | The IATA airport code for the end city of the booking. |
| EndDateLocal | dateTime | Y | The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss. For TripLink suppliers: The time portion of this value will be set to T00:00:00 if the request is from a TripLink - Open Booking Air supplier that does not own the booking. |
| FlightNumber | string | Y | The flight number for the booking. |
| StartCityCode | string | Y | The IATA airport code for the starting address for the booking. |
| StartDateLocal | dateTime | Y | The booking starting time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss. For TripLink suppliers: The time portion of this value will be set to T00:00:00 if the request is from a TripLink - Open Booking Air supplier that does not own the booking. |
| Vendor | string | Y | |
| CancellationNumber | string | The cancellation number from the vendor. This field should be set when you cancel a segment. | |
| CancellationPolicy | string | The cancellation policy from the vendor. | |
| Charges | Parent Element | The charges for this booking. For more information, see the Charges Elements table later on this page. | |
| DateCancelledUtc | dateTime | The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| DateCreatedUtc | dateTime | The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| DateModifiedUtc | dateTime | The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| EndDateUtc | dateTime | Y | The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss. For TripLink suppliers: The time portion of this value will be set to T00:00:00 if the request is from a TripLink - Open Booking Air supplier that does not own the booking. |
| EndGate | string | Y | The arrival gate for the booking. For TripLink suppliers: Will not appear in the response if the request is from a TripLink - Open Booking Air supplier that does not own the booking. |
| EndTerminal | string | Y | The arrival terminal for the booking. For TripLink suppliers: Will not appear in the response if the request is from a TripLink - Open Booking Air supplier that does not own the booking. |
| LegId | string | The leg ID of the booking. Leg IDs do not change on a connection. For each unique leg ID in the trip, all flights subsequent to the first segment with the same leg ID are connections. | |
| Seats | Parent Element | The seats for the booking. This parent element contains an AirSeat element for each included seat. For more information, see the AirSeat Elements table later on this page. | |
| StartDateUtc | dateTime | Y | The booking starting time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss. For TripLink suppliers:The time portion of this value will be set to T00:00:00 if the request is from a TripLink - Open Booking Air supplier that does not own the booking. |
| StartGate | string | Y | The departure gate for the booking. For TripLink suppliers: Will not appear in the response if the request is from a TripLink - Open Booking Air supplier that does not own the booking. |
| StartTerminal | string | Y | The departure terminal for the booking. For TripLink suppliers: Will not appear in the response if the request is from a TripLink - Open Booking Air supplier that does not own the booking. |
| Status | string | The GDS based booking status for the segment such as HK, HL, BK, etc. | |
| TimeZone | string | Y | The time zone of the booking. Format: One of the supported Olson or Windows Time Zones. |
| AircraftCode | string | The code for the aircraft type. | |
| Bags | string | The number of bags included in the booking. | |
| Cabin | string | The section of the airplane for the booking. | |
| CarbonEmissionLbs | decimal | The pounds of carbon emission for this booking. | |
| CarbonModel | integer | The model used to calculate the carbon emissions. | |
| CheckedBaggage | string | Whether the booking includes checked baggage. | |
| Duration | integer | The duration of the booked flight. | |
| ETicket | string | Whether the booking has an e-ticket. Format: Y/N | |
| IsOpenSegment | boolean | Whether the segment is open. Format: True/False | |
| IsPreferredVendor | integer | If the airline is marked as a preferred property by the company. Format: True/False | |
| CreditCardType | String | The type of credit card (for example, Visa/Mastercard/etc.). | |
| CreditCardLastFour | String | The last four digits of credit card number. | |
| IsUpgradeAllowed | boolean | Whether the booking can be upgraded. Format: True/False | |
| Meals | string | The meals included in the booking. | |
| Miles | integer | The number of miles included in the booking. | |
| Notes | string | Additional details about the booking. | |
| OpenSegment | string | Additional information about the open segment. | |
| OperatedByFlightNumber | string | Flight Number provided by the airline operating the flight on behalf of the booked airline. | |
| OperatedByVendor | sring | The airline operating the flight on behalf of the booked airline. | |
| OperatedByVendorName | string | The name of the airline operating the flight on behalf of the booked airline. | |
| Services | string | The services included in the booking. | |
| SpecialInstructions | string | Additional instructions regarding the booking. Max Length: 256 | |
| UpgradedDateTime | dateTime | The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss |
AirSeat Elements
| Element | Data Type | Description |
|---|---|---|
| PassengerRph | integer | The passenger assigned to the seat. |
| SeatNumber | string | The number of the seat. |
CarBooking Elements
The Car Booking parent element is the Car Element in the Segments Array in Booking Elements. This parent element contains a Car Booking child element for each booked car.
| Element | Data Type | TripLink | Description |
|---|---|---|---|
| ConfirmationNumber | string | The confirmation number from the vendor. | |
| EndDateLocal | dateTime | Y | The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss |
| StartDateLocal | dateTime | Y | The booking starting time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss |
| Vendor | string | The two letter GDS vendor code. See the Car Vendor Codes table for car vendor codes. | |
| CancellationNumber | string | The cancellation number from the vendor. This field should be set when you cancel a segment. | |
| CancellationPolicy | string | The cancellation policy from the vendor. | |
| Charges | Parent Element | The charges for this booking. For more information, see the Charges Elements table. | |
| Currency | string | The 3-letter ISO 4217 currency code for the booking. | |
| DailyRate | decimal | The daily rate for the booking. | |
| DateCancelledUtc | dateTime | The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| DateCreatedUtc | dateTime | The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| DateModifiedUtc | dateTime | The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| EndCityCode | string | Y | The IATA airport code for the ending address for the booking. |
| EndDateUtc | dateTime | Y | The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| EndLatitude | string | The latitude for the ending location of the booking. | |
| EndLongitude | string | The longitude for the ending location of the booking. | |
| Notes | string | Additional information about the booking. | |
| PhoneNumber | string | The phone number for the user. | |
| RateCode | string | The rate code for the booking. | |
| StartCityCode | string | Y | The IATA airport code for the starting address for the booking. |
| StartDateUtc | dateTime | Y | The booking starting time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| StartLatitude | string | The latitude for the starting location of the booking. | |
| StartLongitude | string | The longitude for the starting location of the booking. | |
| Status | string | The booking status. | |
| TimeZone | string | Y | The time zone of the booking. Format: One of the supported Olson or Windows Time Zones. |
| TotalRate | decimal | The total rate amount of the booking. | |
| VendorName | string | The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary. | |
| AirCondition | string | The character code that indicates if car has air conditioner. R for AC, N for No AC | |
| Body | string | The character code to indicate how many passengers the car can seat. B for 2-door, D for 4-door, F for Four-wheel drive, J for All Terrain, K for truck, L for Limo, P for pick-up, R for recreation, S for Sport, T for Convertible, V for Van, W for Wagon/Estate, X for special. | |
| Class | string | Character code to indicate the class of the car (for example, if it is economy, full size, compact, etc.). Varies by Vendor. C for compact, E for economy, F for full size, I for Intermediate, L for Luxury, M for Mini, P for Premium, S for Standard, X for special. | |
| DiscountCode | string | The discount code used by the company/TMC to get a discounted rate. | |
| CreditCardType | String | The type of credit card (for example, Visa/Mastercard/etc.). | |
| CreditCardLastFour | String | The last four digits of credit card number. | |
| DropoffCollectionAddress1 | string | The AddressLine1 for the dropoff address when the rental service offers dropoff. | |
| DropoffCollectionAddressType | string | ||
| DropoffCollectionCategory | string | ||
| DropoffCollectionCity | string | City for the dropoff address when the rental service offers dropoff. | |
| DropoffCollectionCityCode | string | The IATA airport code for the dropoff address when the rental service offers dropoff. | |
| DropoffCollectionCountry | string | The country for the dropoff address when the rental service offers dropoff. | |
| DropoffCollectionLatitude | string | The latitude for the dropoff address when the rental service offers dropoff. | |
| DropoffCollectionLongitude | string | The longitude for the dropoff address when the rental service offers dropoff. | |
| DropoffCollectionNumber | string | ||
| DropoffCollectionPhoneNumber | string | The phone number for the dropoff address when the rental service offers dropoff. | |
| DropoffCollectionPostalCode | string | The postal code for the dropoff address when the rental service offers dropoff. | |
| DropoffCollectionState | string | The state for the dropoff address when the rental service offers dropoff. | |
| EndAddress | string | The ending address for the booking. | |
| EndAddress2 | string | The ending address for the booking. | |
| EndCity | string | Y | The ending address for the booking. |
| EndCloseTime | string | The closing time for the dropoff location. | |
| EndCountry | string | Y | The ending address for the booking. |
| EndLocation | string | The dropoff location. | |
| EndOpenTime | string | The opening time of the dropoff location. | |
| EndPhoneNumber | string | The phone number of the dropoff location. | |
| EndPostalCode | string | The ending address for the booking. | |
| EndState | string | Y | The ending address for the booking. |
| FrequentTravelerId | string | The loyalty program ID for the user. | |
| IsUpgradeAllowed | boolean | Whether the booking can be upgraded. Format: True/False | |
| NumCars | unsignedByte | The number of cars rented. | |
| NumPersons | unsignedByte | The number of people including the driver that the rental is for. | |
| PickupDeliveryAddress1 | string | The AddressLine1 for the pickup address when the rental service offers pickup. | |
| PickupDeliveryAddressType | string | ||
| PickupDeliveryCategory | string | ||
| PickupDeliveryCity | string | The city for the pickup address when the rental service offers pickup. | |
| PickupDeliveryCityCode | string | The IATA airport code for the pickup address when the rental service offers pickup. | |
| PickupDeliveryCountry | string | The country for the pickup address when the rental service offers pickup. | |
| PickupDeliveryLatitude | string | The latitude for the pickup address when the rental service offers pickup. | |
| PickupDeliveryLongitude | string | The longitude for the pickup address when the rental service offers pickup. | |
| PickupDeliveryNumber | string | ||
| PickupDeliveryPhoneNumber | string | The phone number for the pickup address when the rental service offers pickup. | |
| PickupDeliveryPostalCode | string | The postal code for the pickup address when the rental service offers pickup. | |
| PickupDeliveryState | string | The state for the pickup address when the rental service offers pickup. | |
| RateType | string | The rate type for the booking. | |
| SpecialEquipment | string | Any special equipment required by the renter. | |
| SpecialInstructions | string | Additional instructions regarding the booking. Max Length: 256 | |
| StartAddress | string | The starting address of the booking. | |
| StartAddress2 | string | The starting address for the booking. | |
| StartCity | string | Y | The starting address for the booking. |
| StartCloseTime | string | The closing time for the pickup location. | |
| StartCountry | string | Y | The starting address for the booking. |
| StartLocation | string | The starting location of the booking. | |
| StartOpenTime | string | The opening time for the pickup location. | |
| StartPostalCode | string | The starting address for the booking. | |
| StartState | string | Y | The starting address for the booking. |
| Transmission | string | The character code that indicates if the car has auto-transmission. A for Auto, M for Manual | |
| UpgradedDateTime | dateTime | The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss |
Hotel Booking Elements
The Hotel Booking parent element is the Hotel Element in the Segments Array in Booking Elements. This parent element contains a Hotel Booking child element for each booked hotel.
| Element | Data Type | TripLink | Description |
|---|---|---|---|
| ConfirmationNumber | string | The confirmation number from the vendor. | |
| EndDateLocal | dateTime | Y | The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss |
| Name | string | The hotel name for the booking. | |
| StartCityCode | string | Y | The IATA airport code for the starting address for the booking. |
| StartDateLocal | dateTime | Y | The booking starting time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss |
| Status | string | Y | The booking status. |
| Vendor | string | The two letter GDS vendor code. See the Hotel Codes table for hotel vendor codes. | |
| CancellationNumber | string | The cancellation number from the vendor. This field should be set when you cancel a segment. | |
| CancellationPolicy | string | The cancellation policy from the vendor. | |
| Charges | Parent Element | The charges for this booking. For more information, see the Charges Elements table. | |
| CheckinTime | string | The check in time for the hotel booking. | |
| CheckoutTime | string | The check out time for the hotel booking. | |
| Currency | string | The 3-letter ISO 4217 currency code for the booking. | |
| CreditCardType | String | The type of credit card (for example, Visa/Mastercard/etc.). | |
| CreditCardLastFour | String | The last four digits of credit card number. | |
| DailyRate | decimal | Average per day rate for the hotel. If the rate varies over the duration, it can be specified using the charges model. | |
| DateCancelledUtc | dateTime | The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| DateCreatedUtc | dateTime | Y | The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| DateModifiedUtc | dateTime | Y | The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| EndDateUtc | dateTime | Y | The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| HotelPropertyId | string | The hotel's property ID. | |
| Notes | string | Additional information about the booking. | |
| NumPersons | unsignedByte | The number of people the booking is for. | |
| NumRooms | unsignedByte | The number of rooms the booking is for. | |
| PhoneNumber | string | The phone number for the booking. | |
| RateCode | string | The rate code for the booking. | |
| RoomDescription | string | The room description for the booking. Max Length: 200 | |
| RoomType | string | The room type for the booking. | |
| SpecialInstructions | string | Additional instructions regarding the booking. Max Length: 256 | |
| StartAddress | string | The starting address of the booking. | |
| StartAddress2 | string | The starting address for the booking. | |
| StartCity | string | Y | The starting address for the booking. |
| StartCountry | string | Y | The starting address for the booking. |
| StartLatitude | string | The latitude for the starting location of the booking. | |
| StartLongitude | string | The longitude for the starting location of the booking. | |
| StartPostalCode | string | The starting address for the booking. | |
| StartState | string | The starting address for the booking. | |
| StartDateUtc | dateTime | Y | The booking starting time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| TimeZone | string | Y | The time zone of the booking. Format: One of the supported Olson or Windows Time Zones. |
| TotalRate | string | The total rate amount of the booking. | |
| EndCityCode | string | The IATA airport code for the ending address for the booking. | |
| DiscountCode | string | The discount code for the booking. | |
| FrequentTravelerId | string | The traveler’s ID for the frequent traveler reward program. | |
| HadDeposit | boolean | Whether the booking had a deposit. Format: true/false | |
| IsUpgradeAllowed | boolean | Whether the booking can be upgraded. Format: true/false | |
| ModificationCode | string | The code for the modification to the booking. | |
| PartnerMembershipId | string | The membership ID of the partner associated with the booking. | |
| PassiveType | string | The type of the booking. | |
| RateAccess | string | The rate access for the booking. | |
| RateType | string | The rate type for the booking. | |
| UpgradedDateTime | dateTime | The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss | |
| VendorFlags | string | Semi-colon-delimited list of flags for free hotel service flags. For example, free breakfast (FB), internet (FI), Parking (FP), etc. If they were all present they can be concatenated as - FB;FI;FP; | |
| VendorName | string | The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary. |
Dining Booking Elements
The Dining Booking parent element is the Dining Element in the Segments Array in Booking Elements. This parent element contains a Dining Booking child element for each booked meal.
| Element | Date Time | TripLink | Description |
|---|---|---|---|
| ConfirmationNumber | string | The confirmation number from the vendor. | |
| CancellationNumber | string | The cancellation number from the vendor. This field should be set when you cancel a segment. | |
| Charges | Parent Element | The charges for this booking. For more information, see the Charges Elements table later on this page. | |
| DateCancelledUtc | dateTime | The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| DateCreatedUtc | dateTime | The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| DateModifiedUtc | dateTime | The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| EndDateLocal | dateTime | The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss | |
| EndDateUtc | dateTime | The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| FrequentTravelerId | string | The loyalty program ID for the user. | |
| IsUpgradeAllowed | boolean | Whether the booking can be upgraded. Format: true/false | |
| Name | string | The name of the restaurant. Maximum length: 80 | |
| Notes | string | Additional information about the booking. | |
| NumPersons | unsignedByte | The number of persons for the booking. | |
| PhoneNumber | string | The restaurant phone number. | |
| RestaurantId | string | The booking vendor’s restaurant ID. Maximum length: 50 | |
| StartAddress | string | The restaurant address. Maximum length: 80 | |
| StartAddress2 | string | The restaurant address. Maximum length: 80 | |
| StartCity | string | The restaurant address. Maximum length: 50 | |
| StartCountry | string | The restaurant address. | |
| StartDateLocal | dateTime | The booking starting time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss | |
| StartDateUtc | dateTime | The booking starting time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| StartLatitude | string | The latitude of the restaurant. | |
| StartLongitude | string | The longitude of the restaurant. | |
| StartPostalCode | string | The restaurant address. Maximum length: 24 | |
| StartState | string | The restaurant address. Maximum length: 50 | |
| Status | string | The status of the segment. | |
| TimeZone | string | The time zone of the booking. Format: One of the supported Olson or Windows Time Zones. | |
| UpgradedDateTime | dateTime | The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss | |
| Vendor | string | The two letter GDS vendor code. | |
| VendorName | string | The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary. |
Ride Booking Elements
The Ride Booking parent element is the Ride Element in the Segments Array in Booking Elements. This parent element contains a Ride Booking child element for each booked ride.
| Element | Data Type | TripLink | Description |
|---|---|---|---|
| ConfirmationNumber | string | The confirmation number from the vendor. | |
| EndCityCode | string | The ending IATA airport code of the booking. | |
| StartCityCode | string | The starting IATA airport code of the booking. | |
| Vendor | string | The two letter GDS vendor code. See the Ride Codes table for ride vendor codes. For an unknown vendor, use the code value $$. | |
| CancellationNumber | string | The cancellation number from the vendor. This field should be set when you cancel a segment. | |
| CancellationPolicy | string | The cancellation policy from the vendor. | |
| Currency | string | The 3-letter ISO 4217 currency code for the booking. | |
| DateCancelledUtc | dateTime | The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| DateCreatedUtc | dateTime | The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| DateModifiedUtc | dateTime | The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| DropoffInstructions | string | Instructions regarding the booking. | |
| Duration | integer | The duration of the booking. | |
| EndAddress | string | The ending address of the booking. | |
| EndAddress2 | string | The ending address of the booking. | |
| EndCity | string | The ending address of the booking. | |
| EndCountry | string | The ending address of the booking. | |
| EndDateLocal | dateTime | The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss | |
| EndDateUtc | dateTime | The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| EndLatitude | string | The latitude for the ending location of the booking. | |
| EndLocation | string | The ending location of the booking. | |
| EndLocationCode | string | The ending location code of the booking. | |
| EndLocationName | string | The ending location name of the booking. | |
| EndLongitude | string | The longitude of the ending point of the booking. | |
| EndPostalCode | string | The ending address of the booking. | |
| EndState | string | The ending address of the booking. | |
| IsPersonal | boolean | Whether the segment is for personal travel. Format: true/false. | |
| IsUpgradeAllowed | boolean | Whether the booking can be upgraded. Format: true/false | |
| MeetingInstructions | string | The instructions for the meeting location of the booking. | |
| Miles | integer | The number of miles for the booking. | |
| Name | string | The name on the booking. | |
| Notes | string | Additional information about the booking. | |
| NumberOfHours | double | The number of hours of the booking. | |
| NumPersons | unsignedByte | The number of people included in the booking. | |
| OperatedByVendor | string | The operated by vendor for the booking. | |
| PassiveCityCode | string | The passive city code of the booking. | |
| PhoneNumber | string | The ride vendor phone number. | |
| PickupInstructions | string | Instructions regarding the booking. | |
| Rate | string | The rate for the booking. | |
| RateDescription | string | The rate description for the booking. | |
| RateNotes | string | The rate notes for the booking. | |
| RateType | string | The rate type for the booking. | |
| ReservationId | string | The booking vendor’s reservation ID. | |
| SpecialInstructions | string | The special instructions for the ride. Max Length: 256 | |
| StartAddress | string | The starting address of the booking. | |
| StartAddress2 | string | The starting address of the booking. | |
| StartCity | string | The starting address of the booking. | |
| StartCountry | string | The starting address of the booking. | |
| StartDateLocal | dateTime | The booking starting time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss | |
| StartDateUtc | dateTime | The booking starting time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| StartLatitude | string | The latitude of the booking start location. | |
| StartLocation | string | The starting location of the booking. | |
| StartLocationCode | string | The code of the starting location of the booking. | |
| StartLocationName | string | The name of the starting location of the booking. | |
| StartLongitude | string | The longitude of the booking start location. | |
| StartPostalCode | string | The starting address of the booking. | |
| StartState | string | The starting address of the booking. | |
| Status | string | The status of the segment. | |
| TimeZone | string | The time zone of the booking. Format: One of the supported Olson or Windows Time Zones. | |
| UpgradedDateTime | dateTime | The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss | |
| VendorName | string | The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary. | |
| Charges | Parent Element | The charges for this booking. For more information, see the Charges Elements table. |
Rail Booking Elements
The Rail Booking parent element is the Rail Element in the Segments Array in Booking Elements. This parent element contains a Rail Booking child element for each booked rail segment.
| Element | Data Type | TripLink | Description |
|---|---|---|---|
| ConfirmationNumber | string | The confirmation number from the vendor. | |
| StartDateLocal | dateTime | Y | The starting date of travel for this segment, in the local time of to the starting point. Format: YYYY-MM-DDThh:mm:ss |
| Amenities | string | The booked amenities. | |
| Cabin | string | The cabin identifier. | |
| CancellationNumber | string | The cancellation number from the vendor. This field should be set when you cancel a segment. | |
| CarbonEmissionLbs | decimal | The pounds of carbon emission for this booking. | |
| CarbonModel | integer | The model used to calculate the carbon emissions. | |
| ClassOfService | string | The class of the booking. | |
| CreditCardType | String | The type of credit card (for example, Visa/Mastercard/etc.). | |
| CreditCardLastFour | String | The last four digits of credit card number. | |
| Currency | string | The 3-letter ISO 4217 currency code for the booking. | |
| DateCancelledUtc | dateTime | The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| DateCreatedUtc | dateTime | The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| DateModifiedUtc | dateTime | The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| DiscountCode | string | The discount code for the booking. | |
| Duration | integer | The duration of the trip booked. | |
| EndCity | string | The end city for the rail trip. | |
| EndCityCode | string | The IATA airport code for the end city of the trip. | |
| EndCountry | string | The country code for the booking. | |
| EndDateLocal | dateTime | Y | The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss |
| EndDateUtc | dateTime | Y | The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| EndLatitude | string | The latitude of the ending point of the booking. | |
| EndLongitude | integer | The longitude of the ending point of the booking. | |
| EndPlatform | string | The ending platform location of the booking. | |
| EndRailStation | string | Y | The code for the ending station of the booking. |
| EndRailStationName | string | Y | The name of the ending station of the booking. |
| ETicket | integer | The e-ticket number. | |
| FareType | string | The type of fare on the rail booking. | |
| FrequentTravelerId | string | The traveler’s ID for the frequent traveler reward program. | |
| IsUpgradeAllowed | boolean | Whether the booking can be upgraded. Format: true/false | |
| LegId | string | The trip leg ID. | |
| Meals | string | The booked meals. | |
| Miles | integer | The number of miles booked. | |
| Notes | string | Additional information about the booking. | |
| NumPersons | unsignedByte | The number of persons booked for the trip. | |
| NumStops | unsignedByte | The number of stops in the booking. | |
| OperatedByTrainNumber | string | The train identifier of the operating vendor of the booked trip. | |
| OperatedByVendor | string | The operating vendor of the booked trip. | |
| RateCode | string | The vendor's code for the rate of the booking. | |
| RouteRestrictCode | string | The code to restrict the route of the booking. | |
| SpecialInstructions | string | The instructions for the booking. Max Length: 256 | |
| StartCity | string | The starting city of the booking. | |
| StartCityCode | string | Y | The IATA airport code for the starting city of the booking. |
| StartCountry | string | The starting country of the booking. | |
| StartDateUtc | dateTime | Y | The starting date of travel for this segment, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| StartLatitude | string | The latitude of the starting location of the booking. | |
| StartLongitude | string | The longitude of the starting location of the booking. | |
| StartPlatform | string | The starting platform location of the booking. | |
| StartRailStation | string | Y | The code of the starting station of the booking. |
| StartRailStationName | string | Y | The name of the starting station of the booking. |
| Status | string | The booking status. | |
| TimeZone | string | The time zone of the booking. Format: One of the supported Olson or Windows Time Zones. | |
| TotalRate | decimal | The total rate amount of the booking. | |
| TrainNumber | string | The number for the booked train. | |
| TrainTypeCode | string | The code for the type of train used in the booking. | |
| TrainTypeName | string | The name of the type of train used in the booking. | |
| TransportMode | sring | The transport mode of the booking. | |
| UpgradedDateTime | dateTime | The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss | |
| Vendor | string | The two letter GDS vendor code. | |
| VendorName | string | The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary. | |
| WagonNumber | string | The wagon number of the train car. | |
| Charges | Parent Element | The charges for this booking. For more information, see the Charges Elements table. | |
| Seats | Parent Element | The booked seats. This parent element contains a RailSeat element for each included seat. For more information, see the RailSeat Elements table later on this page. |
RailSeat Elements
| Element | Data Type | TripLink | Description |
|---|---|---|---|
| Amenities | string | The amenities for the seat. | |
| BerthPosition | string | The berth location of the seat. | |
| Deck | string | Which deck the seat is on. | |
| FacingForward | string | Whether the seat is facing forward. | |
| FareSpaceComfort | string | The space around the seat. | |
| PassengerRph | integer | Which passenger the seat is assigned to. | |
| SeatNumber | string | The number of the seat. | |
| SeatPosition | string | The location of the seat. | |
| SpaceType | string | The type of space around the seat. | |
| Status | string | The status of the seat booking. | |
| WagonNumber | string | The number of the wagon the seat is on. | |
| WagonType | string | The type of wagon the seat is on. |
Parking Booking Elements
The Parking Booking parent element is the Parking Element in the Segments Array in Booking Elements. This parent element contains a Parking Booking child element for each booked parking.
| Element | Data Type | TripLink | Description |
|---|---|---|---|
| ConfirmationNumber | string | The confirmation number from the vendor. | |
| StartDateLocal | dateTime | The starting date of travel for this segment, in the local time of to the starting point. Format: YYYY-MM-DDThh:mm:ss | |
| CancellationNumber | string | The cancellation number from the vendor. This field should be set when you cancel a segment. | |
| ClassOfService | string | The class of the booking. | |
| Currency | string | The 3-letter ISO 4217 currency code for the booking. | |
| DateCancelledUtc | dateTime | The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| DateCreatedUtc | dateTime | The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| DateModifiedUtc | dateTime | The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| EndDateLocal | dateTime | The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss | |
| EndDateUtc | dateTime | The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| FrequentTravelerId | string | The traveler’s ID for the frequent traveler reward program. | |
| IsUpgradeAllowed | boolean | Whether the booking can be upgraded. Format: true/false | |
| Notes | string | Additional information about the booking. | |
| OperatedByVendor | string | The operating vendor of the booking. | |
| ParkingLocationId | string | The location of the parking booking. | |
| PhoneNumber | string | The parking phone number. | |
| Pin | string | The PIN number for the booking. | |
| RateCode | string | The vendor's code for the rate of the booking. | |
| StartAddress | string | The starting address of the booking. | |
| StartAddress2 | string | The starting address of the booking. | |
| StartCity | string | The starting address of the booking. | |
| StartCityCode | string | The IATA airport code for the starting city of the booking. | |
| StartCountry | string | The starting address of the booking. | |
| StartDateUtc | dateTime | The starting date of travel for this segment, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| StartLocation | string | The parking location. | |
| StartPostalCode | string | The starting address of the booking. Maximum length: 24 | |
| StartState | string | The starting address of the booking. Maximum length: 50 | |
| Status | string | The booking status. | |
| TimeZone | string | The time zone of the booking. Format: One of the supported Olson or Windows Time Zones. | |
| TotalRate | string | The total rate amount of the booking. | |
| UpgradedDateTime | dateTime | The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss | |
| Vendor | string | The two letter GDS vendor code. | |
| VendorName | string | The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary. | |
| Charges | Parent Element | The charges for this booking. For more information, see the Charges Elements table later on this page. |
Travel Booking Elements
The Travel Booking parent element is the Travel Element in the Segments Array in Booking Elements. This parent element contains a Travel Booking child element for each booked travel request.
NOTE: This booking type is used by the Concur Travel Request product to store the main destination for the trip without specifying a transport type.
| Element | Data Type | TripLink | Description |
|---|---|---|---|
| CancellationNumber | string | The cancellation number from the vendor. This field should be set when you cancel a segment. | |
| ConfirmationNumber | sring | The confirmation number from the vendor. | |
| CreditCardType | String | The type of credit card (for example, Visa/Mastercard/etc.). | |
| CreditCardLastFour | String | The last four digits of credit card number. | |
| Currency | string | The 3-letter ISO 4217 currency code for the booking. | |
| DailyRate | decimal | Average per day rate for the booking. If the rate varies over the duration, it can be specified using the charges model. | |
| DateCancelledUtc | dateTime | The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| DateCreatedUtc | dateTime | The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| DateModifiedUtc | dateTime | The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| EndAddress | string | The ending address of the booking. | |
| EndAddress2 | sring | The ending address of the booking. | |
| EndCity | string | The ending address of the booking. | |
| EndCityCode | string | The IATA airport code for the ending city of the booking. | |
| EndCountry | string | The ending address of the booking. | |
| EndDateLocal | dateTime | The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss | |
| EndDateUtc | dateTime | The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| EndLatitude | string | The latitude for the ending location of the booking. | |
| EndLocation | sring | The ending location of the booking. | |
| EndLongitude | string | The longitude of the ending point of the booking. | |
| EndPostalCode | string | The ending address of the booking. | |
| EndState | sring | The ending address of the booking. | |
| TransportMode | string | The transport mode of the booking. | |
| Notes | string | Additional information about the booking. | |
| NumPersons | unsignedByte | The number of persons booked for the trip. | |
| PhoneNumber | string | The booking phone number. | |
| SpecialInstructions | sring | The instructions for the booking. Max Length: 256 | |
| StartAddress | string | The starting address of the booking. | |
| StartAddress2 | string | The starting address of the booking. | |
| StartCity | sring | The starting address of the booking. | |
| StartCityCode | string | The IATA airport code for the starting city of the booking. | |
| StartCountry | string | The starting address of the booking. | |
| StartDateLocal | dateTime | The starting date of travel for this segment, in the local time of to the starting point. Format: YYYY-MM-DDThh:mm:ss | |
| StartDateUtc | dateTime | The starting date of travel for this segment, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| StartLatitude | string | The latitude of the booking. | |
| StartLongitude | sring | The longitude of the booking. | |
| StartPostalCode | string | The starting address of the booking. Maximum length: 24 | |
| StartState | string | The starting address of the booking. Maximum length: 50 | |
| Status | string | The booking status. | |
| TimeZone | sring | The time zone of the booking. Format: One of the supported Olson or Windows Time Zones. | |
| TotalRate | decimal | The total rate amount of the booking. | |
| Vendor | string | The two letter GDS vendor code. | |
| VendorName | string | The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary. | |
| Charges | Parent Element | The charges for this booking. For more information, see the Charges Elements table. |
Charges Elements
| Element | Data Type | TripLink | Description |
|---|---|---|---|
| Percent | Parent Element | The percent of fixed charges. For more information about the child elements of this parent element, see the Percent Elements table. | |
| Fixed | Parent Element | The fixed charges. For more information about the child elements of this parent element, see the Fixed Elements table. | |
| Rate | Parent Element | The rate for the booking. For more information about the child elements of this parent element, see the Rate Elements table. | |
| RateWithAllowance | Parent Element | The rate for the booking, including any travel allowances. For more information about the child elements of this parent element, see the RateWithAllowance Elements table. |
Rate Elements
| Element | Data Type | Description | |
|---|---|---|---|
| Amount | decimal | The total amount for the rate for the booking. | |
| Currency | string | The 3-letter ISO 4217 currency code for the total amount. | |
| Description | string | The description for the rate. | |
| IsPaid | boolean | Whether the rate has been paid. Format: true/false. | |
| IsPrimary | boolean | Whether the rate is primary. Format: true/false. | |
| NumUnits | decimal | The number of units expected for the charge. For instance, 3 days | |
| PerUnit | string | The unit of measure for the charge. Values represent rates like per DAY, WEEK, or MONTH | |
| SemanticsCode | string | Indicates the charge category for the line item. Refer to the Semantics Codes table for more information. | |
| SemanticsVendorType | string | The vendor type: H=Hotel, C=Car, A=Air, G=Ground, R=Rail | |
| StartDateLocal | dateTime | The start date of the booking, in the user's local time. Format: YYYY-MM-DDThh:mm:ss | |
| Vendor | string | The vendor for the booking charge. | |
| VendorChargeCode | string | The vendor's code for the charge. |
RateWithAllowance Elements
| Element | Data Type | TripLink | Description |
|---|---|---|---|
| AllowanceAmount | decimal | The cost of overage fees when the allowance is exceeded. For example, if the allowance is 5000 miles, the cost could be $0.02 per mile. The overage must be in the same currency as the basic rate. | |
| AllowanceIsUnlimited | boolean | Whether the allowance is unlimited. Format: true/false. | |
| AllowanceNumUnits | decimal | The number of units for the allowance associated with the charge. For example, 5000 miles. | |
| AllowanceUnit | string | The unit of measure for the allowance associated with the charge. For example, a car weekly rate might allow 5000 miles included in the rate. | |
| Amount | decimal | The total amount for the rate for the booking. | |
| Currency | string | The 3-letter ISO 4217 currency code for the total amount. | |
| Description | string | The description for the rate. | |
| IsPaid | boolean | Whether the rate has been paid. Format: true/false. | |
| IsPrimary | boolean | Indicates whether the charge is the Primary or Main rate. For example, if one of the rates is the actual rate and the rest are penalties, the actual rate should be set as IsPrimary. Only one charge in a set should be primary. Format: true/false. | |
| NumUnits | decimal | The number of units expected for the charge. For instance, 3 days. | |
| PerUnit | string | The unit of measure for the charge. Values represent rates like per DAY, WEEK, or MONTH | |
| SemanticsCode | string | Indicates the charge category for the line item. Refer to the Semantics Codes table for more information. | |
| SemanticsVendorType | string | The vendor type: H=Hotel, C=Car, A=Air, G=Ground, R=Rail | |
| StartDateLocal | dateTime | The start date of the booking, in the user's local time. Format: YYYY-MM-DDThh:mm:ss | |
| Vendor | string | The vendor for the booking charge. | |
| VendorChargeCode | string | The vendor's code for the charge. |
Car Vendor Codes
The following car vendor codes are used in the Car Booking Elements.
| Vendor Code | Vendor Name |
|---|---|
| FA | Able |
| AC | Ace |
| AD | Advantage |
| AL | Alamo |
| LV | Allstate |
| AF | Americar |
| ZU | AutoEurope |
| ZI | Avis |
| CH | Charlie |
| CP | Compass |
| CO | Continental |
| DS | Discount |
| ZR | Dollar |
| ET | Enterprise |
| ED | Eurodollar |
| EP | Europcar |
| FH | Falles Hire Cars |
| FD | Ford Dealer |
| HO | Holiday Car |
| IM | Imperial |
| IA | Independent Auto |
| TS | Intl Travel |
| KG | Kemwel Holiday |
| KN | Kenning |
| LL | Localiza |
| ZW | Montgomery Ward |
| NE | Nationwide |
| ZA | Payless |
| PI | Pinellas |
| BL | Red And Blue |
| RR | Rent Rite |
| RS | Resort |
| ZS | Sears |
| SX | Sixt |
| ZT | Thrifty |
| CC | Country Car |
| TR | Triangle |
| CT | TT/Key Services |
| SV | U-Save |
| CY | Carey International |
| CV | Capps Vans |
| AB | All American |
| EE | Exoticar Express |
| LX | Limo Service |
| MW | Midway |
| NF | New Frontier |
| SL | SL I.T.S. |
| US | US Rent a Car |
| VR | Specialty Van |
| WC | West Coast |
| ZH | Simply Wheelz |
| NU | Nu Car Rentals |
| EY | Economy Rent a Car |
| $$ | Unknown Car Vendor |
| ZM | Zoom Rent a Car |
| ZD | Budget |
| ZE | Hertz |
| ZL | National |
| AU | Austrian |
| DR | DER Travel Svcs |
| EN | Vip Car Rental |
| ML | Merlin |
| EZ | Ez Rent A Car |
| FX | Fox |
| LM | L & M Car Rental |
| SW | Southwest |
| NW | New Frontier |
Hotel Vendor Codes
| Vendor Code | Vendor Name |
|---|---|
| RT | AccorHotels |
| AM | Adams Mark |
| AZ | The Ascott Limited |
| AS | All Suites |
| AR | AC Hoteles |
| AJ | AmeriSuites |
| AN | Ana Hotels |
| AX | Anasazi Service |
| AQ | ATA Hotels |
| AO | Atlantis Hotel |
| AH | Aston Hotels |
| AP | Andre Balazs |
| AC | Atel France |
| BB | Bartell Hotels |
| BW | Best Western |
| BM | Biltmore |
| BU | Baymont Inns |
| CJ | Caesar Park |
| QC | Camberly |
| CA | Confortel |
| CO | Camino Real Htls |
| CV | COMO Hotels and Resorts |
| CE | Chalet Susse |
| CR | Clarion |
| CH | CIH Hotels |
| WX | Coast Hotels |
| CS | Classical Hotels |
| CI | Comfort Inns |
| CD | Concord Hotels |
| WA | Waldorf Astoria |
| BC | Boutiquw |
| CX | Country Inn |
| CL | Corus Hotels |
| DC | Dorchester Htls |
| DE | Delta Hotels |
| DS | Design Hotels |
| FT | Grande Hotels |
| DV | De Vere |
| DA | Doral Hotels |
| DO | Dorintresorts |
| DT | Doubletree |
| DY | Doyle Hotels |
| DR | Drury Inns |
| EE | Marriott Exec Ap |
| EO | Econo Lodge |
| ER | Electronic Rep |
| EU | Exclusive Htls |
| RM | Hetras |
| XH | Extra Holidays |
| FA | Fairmont Hotels |
| FQ | Fauriel |
| FM | Fiesta American |
| FE | Forte Hotels |
| FS | Four Seasons |
| FZ | Friendship Inns |
| FC | Rocco Forte |
| GX | Global Conextion |
| HN | Linkhotel |
| GR | Six Senses Hotel |
| GT | Golden Tulip |
| AG | Gouverner Hotel |
| GN | Gramercy Park Hotel |
| GH | Grand Heritage |
| GD | Grand Tradition |
| HB | Hbs Hotel Booki |
| HX | Hampton Inns |
| HR | Harrah's |
| HV | Harvey Hotels |
| HP | Hyatt Place |
| BH | Hawthorn Suites |
| HL | Hilton Intl |
| BE | Homestead Studio |
| HG | Homewood Suites |
| HO | Hotelrez |
| AI | Armani Hotels |
| HW | Hotel World |
| HQ | Hotelink Intl |
| HA | HOTUSA Hotels |
| MR | Morgans Hotel Group |
| IL | Innlink Res Svc |
| IP | InnPoints |
| IG | Insignia Resorts |
| IC | InterContinental |
| IE | InterEurope Htls |
| IT | Intl Trvl Resort |
| TS | Intl Trvl Svcs |
| IR | Innpoints |
| JA | Jarvinen Hotels |
| JY | Jolly Hotels |
| KA | Karos Hotels |
| KI | Kempinski |
| KY | Keytel |
| KC | Kimpton Hotels |
| KN | Kintetsu Intl |
| NV | Las Vegas Travel |
| LW | Leading Hotels |
| LM | Vantis Hotel GRP |
| LA | Little America |
| LZ | Loews Hotels |
| LR | LRI |
| LU | Luxor Hotel |
| MY | Personality Hotels |
| MZ | Mainstay Suites |
| MO | Mandarin Orientl |
| MH | Marco Polo Htls |
| MM | Maritim Hotels |
| ET | Marriott Cnf Ctr |
| MG | Magnolia Hotels |
| MF | Micros Fidelio |
| MT | Microtel Hotels |
| MU | Millennium Htls |
| MP | Mantra Group |
| MN | Montage Hotels A |
| MI | Malmaison Hotels |
| MK | Movenpick Htls |
| ND | National Hotels |
| NO | New Otani |
| NK | Nikko Hotels |
| NH | Nippon Travel |
| OB | Oberoi Group |
| OC | Okura Hotels |
| OM | Omni Hotels |
| OH | Oslo Hotel |
| OR | Outrigger |
| PS | Sandman Hotels |
| PF | Pan Pacific |
| PL | Parkroyal Hotels |
| PQ | Purple Hotels |
| PH | Preferred Hotels |
| PW | Prima Hotels |
| PN | Peninsula Hotels |
| PR | Protea Hotels |
| QI | Quality Inns |
| QL | Queens Hotels |
| QM | Queens Moat Htls |
| QH | QHotels |
| RD | Radisson |
| NR | Ramada Intl |
| ON | Reconline |
| RL | Red Lion Inns |
| RF | Red Roof Inns |
| RQ | Regal Hotels |
| KR | Regal Hotels UK |
| RE | Regent Intl |
| RH | Reservations Hub |
| BR | Renaissance Intl |
| RC | Residence Inns |
| RR | Righa Royal |
| RZ | Ritz-Carlton |
| RW | Rosewood |
| RI | Rodeway Inns |
| RO | Rotana Hotels and Resorts |
| RB | Resort Bookings |
| RG | Rydges Group |
| SH | Scandic Hotels |
| IQ | Myfidelio |
| SC | Sceptre Hotels |
| SQ | Select Hotels |
| SG | Shangri-La |
| BP | Shilo Inns |
| US | Sierra Hotels |
| SJ | Jameson Inns |
| SZ | Sleep Inns |
| SB | Sofitel |
| LX | Small Luxury |
| SM | InnLink Res Svc |
| SN | Sonesta Hotels |
| ST | Sorat Hotels |
| SP | Special Prop-IHG |
| XV | SpringHill Suites |
| SR | Steigenberger |
| SK | Stakis Hotels |
| YS | Stamford Hotels |
| LV | Las Vegas Test |
| YZ | Staybridge Ste |
| WR | Sterling Intl |
| SS | Studio 6 |
| XL | Summit Hotels |
| SX | Supranational |
| UK | Swallow Hotels |
| SL | Swissotel |
| TI | Thistle Hotels |
| TM | Tianma |
| TP | Top Intnl Htls |
| TH | Trident Hotels |
| TO | TownePlace Suites |
| TA | Reservhotel |
| TX | Treff Hotels |
| TR | Cendant Trip Rewards |
| VP | VIP Intl |
| VA | OneTech Solution |
| VI | Vienna International |
| WH | W Hotels |
| DW | Walt Disney Htl |
| WK | Warwick Hotels |
| WL | Wellesley Inns |
| WM | Westmark Hotel |
| EJ | Williams |
| WC | WestCoast Hotels |
| WW | World Hotels |
| WY | Wyndham Hotels |
| SW | Starwood (All) |
| AL | Aloft Hotels |
| BY | Banyan Tree |
| EL | Elements |
| GA | Global Alliance |
| IW | Hotels & Preference |
| QX | Luxury Lifestyle |
| RP | Rendezvous Hospitality Group |
| RU | Hard Rock |
| TY | Tradyso Global Distribution |
| ZX | Marriott Affliat |
| TB | GTA TravelBound |
| DX | Dolce Hotels |
| JI | Jurys Inns |
| LD | Leonardo |
| LJ | Lalit |
| NZ | Ascend |
| IN | Indigo Hotels |
| LC | Luxury Collection |
| LI | LeisureLink Inc |
| OT | Othon Hotels |
| PX | Performance Conn |
| PY | Peabody Hotels |
| SE | Sercotel |
| WF | West Coast Famil |
| ZC | Ritz Club |
| XO | Luxury Resorts |
| AT | Address Hotels |
| CQ | Club Quarters |
| ML | Melrose Hotels |
| DH | Distinguished Hotels |
| PI | Premier Inn |
| ZZ | Independent |
| JT | Jumeirah |
| EZ | Cambria Suites |
| UB | Suburban Extended Stay |
| FB | Fontainebleau |
| GV | Graves Hotels |
| IM | Independent Htls |
| JL | Jumeriah |
| LP | Lexington |
| OP | Omni Partners |
| PV | Preferred Group |
| RJ | Resort Condos |
| RK | Rezlink Intl |
| UV | Univisit |
| VK | Vacationclick |
| VR | Vacation Rentals |
| XN | Global Res |
| XX | New Synxis |
| XZ | Hotelzon |
| OI | Amadeus LinkHotel |
| GF | Grange Hotels |
| EP | Epoque Hotels |
| LO | Langham Hotels |
| PM | Barcelo Hotels |
| QV | ResortQuest Intl |
| XW | WebRes |
| YH | Booking Services |
| YP | Altiuspar Soluti |
| DD | Derag Hotels |
| XR | St Regis |
| 6C | Intercontinental Hotels Group |
| AB | Abba Hotels |
| AE | AmeriHost Inn |
| AV | Allegience Svcs |
| AW | Astra Worldwide |
| BA | Boscolo Hotels |
| BG | Bulgari Hotels |
| BN | Barcelo Hotels |
| BV | Best Value Inns |
| CG | City Lodge Group |
| CN | Conrad |
| CP | Crowne Plaza |
| CU | Charming Hotels |
| CW | Carlson Brands (All) |
| CZ | Comfort Suites |
| DI | Days Inn |
| DM | Domina Hotels |
| DU | Destinations Unl |
| EC | Choice Brands |
| EH | Hilton (All) |
| EK | Sercotel |
| EM | Marriott (All) |
| GI | Hilton Garden Inn |
| GM | Meritus |
| GW | Great Hotels |
| HE | Historic Hotels |
| HF | HomeGate Studios |
| HU | Hyatt Vacation |
| ID | Resnet |
| IF | ACC-NIFOS |
| IS | Ian Schrager |
| IU | Intourist Travel |
| JC | Cendant Brands (All) |
| JU | Jumer |
| KL | ClubHouse Inns |
| LT | Travelodge AU |
| MS | Magnuson Hotels |
| MV | MGM Mirage |
| NN | Louvre Hotels |
| NY | Denihan Hospitality Group |
| OE | Orient Express |
| OK | Alesia |
| OS | Sweden Hotels |
| PK | Park Plaza Intl |
| PT | Prime Hotels |
| RA | Ramada Hotels |
| RN | Expotel |
| RX | Ringhotels |
| SO | Sonesta |
| SV | Sarova Hotels |
| SY | Starhotels |
| TL | Travelodge |
| TV | ReservHotel |
| VC | Marriott Vacation Club |
| WD | Chase Suite Hotels |
| WG | Wingate Inn |
| XS | Summerfield Suites |
| II | Indecorp |
| GZ | Genares Worldwide |
| GE | Gaylord Hotels |
| FV | Flairview |
| EW | Exclusive World |
| GQ | Genre Hotels |
| FX | First Hotel |
| WT | Tryp by Wyndham |
| UN | Carino Hotels |
| GP | Husa Hotels |
| IV | InnVite |
| LG | Lindner Hotels |
| JJ | Jin Jiang Hotels |
| CK | Black Pepper Hotels |
| QO | Swiss Quality Hotels |
| AK | Autograph |
| EB | Edition |
| EQ | Eaton |
| FD | Etours |
| HM | Missoni |
| JG | JG Black Book |
| OO | One And Only |
| UA | Premier Connect |
| PU | Pullman |
| QG | Quest |
| TW | Trump Hotel Collection |
| TF | Thon Hotels |
| IA | Corinthia Hotels |
| NU | Northwood Hospitality |
| HC | hotel.de |
| $$ | Unknown Hotel Vendor |
| QU | Aqua Hotels and Resorts |
| FG | FastBooking |
| BL | Balladins Hotels |
| ZW | CWT Private Hotels |
| DN | Destination |
| XE | Excalibur |
| CY | Courtyard |
| ES | Embassy Suites |
| FN | Fairfield Inns |
| HH | Hilton |
| HI | Holiday Inn |
| HJ | Howard Johnson |
| HY | Hyatt |
| MC | Marriott |
| SI | Sheraton |
| WI | Westin |
| CB | Classic British |
| HT | Home2 Suites |
| JH | Jumer Hotels |
| LQ | La Quinta Inns |
| QR | Quality Htl Res |
| SU | Southern Sun |
| UI | Utell |
| PD | Park Inn |
| SF | Sutton Place Htl |
| YO | Candlewood Stes |
| KG | Knights Inn |
| VG | Villager |
| OZ | Super 8 |
| VY | Maybourne Hotels |
| JD | Doyle Collection |
| EA | Extended Stay |
| VE | Vantis Hotels |
| YX | Synxis Res Svcs |
| BK | Interstate Hotels and Resorts |
| MD | Le Meridien |
| LE | Luxe Worldwide |
| KH | K Hotels |
| FW | Flag Hotels |
| UZ | Unirez |
| GO | Guesthouse International |
| TG | Travelodge UK |
| WO | WorldRes |
| JV | Joie De Vivre |
| PJ | Prince Resorts |
| BI | Best Inns |
| MB | Mandalay Bay |
| YR | Raffles Intl |
| FH | Fiesta Americana |
| NS | NH Hotels |
| NC | Noble House |
| OG | Olympus Hospitality |
| RS | Rockresorts Intl |
| GB | MacDonald Group |
| WB | Relais/Chateaux |
| GG | Grand Hosp. |
| AA | AmericInns |
| MX | Motel 6 |
| DL | Doral Resorts |
| CC | Clarion |
| BT | BT Advantage |
| SA | Sabre Exclusives |
| RV | Red Roof Inns |
| TJ | Taj Hotels |
| BX | Columbus Res Svc |
| BZ | Cmnet Brazil |
| CM | Camino Real |
| DJ | Hotel Port |
| EI | Executive Hotels |
| HK | Hot Key Intl. |
| IH | CIH Hotels |
| KO | KSL Resorts |
| ME | Sol Melia |
| NW | Newtrade |
| PG | Phillips Hotel |
| UE | Universal Resort |
| WS | World Res |
| WV | TravelCLICK |
Ride Vendor Codes
| Vendor Code | Vendor Name |
|---|---|
| $R | RideCharge |
| AL | AddisonLee |
| DG | DeemGroundLimo |
| GC | GroundScope |
| GS | GroundSpan |
| LC | Limoscom |
| SQ | SummitQwest |
| SW | SummitQwest |
| TD | Tandem |
| TV | Transvip |
Semantics Codes
The semantics codes are used in the Charges child elements in Bookings.
| Vendor Type | Semantics Code | Description |
|---|---|---|
| Hotel | OTHER | Other miscellaneous charges |
| Hotel | BUSINESS | Business center charges |
| Hotel | CONFERENCE | Conference charges |
| Hotel | COUNTYTAX | County tax |
| Hotel | VAT | VAT tax |
| Hotel | GST | GST tax |
| Hotel | FEDERALTAX | Federal tax |
| Hotel | FOOD | Food/beverage charges: hotel restaurant, room service |
| Hotel | ALCOHOL | Alcohol charges: beer, wine, and liquor at restaurant |
| Hotel | FOODTAX | Food/beverage taxes |
| Hotel | GIFT | Gift shop charges |
| Hotel | GENERALTAX | General taxes |
| Hotel | HEALTH | Health club, pool, court, golf, etc. |
| Hotel | LAUNDRY | Laundry |
| Hotel | MINIBAR | In room mini-bar |
| Hotel | CITYTAX | City tax |
| Hotel | MOVIE | Movie, in room entertainment |
| Hotel | GAME | Game, in room entertainment |
| Hotel | PARKING | Parking/Valet |
| Hotel | PST | PST tax |
| Hotel | STATETAX | State tax |
| Hotel | PAYMENT | Payment |
| Hotel | DISCOUNT | Discount |
| Hotel | ROOMRATE | Room rate |
| Hotel | ROOMTAX | Room tax |
| Hotel | GRATUITY | Gratutities, tips |
| Hotel | PHONE | Telephone charges |
| Hotel | INTERNET | Internet charges |
| Hotel | NOSHOW | No show fee |
| Hotel | NEGOTIATEDRATE | Negotiated room rate |
| Car | DAYS | DAYS |
| Car | WEEKS | WEEKS |
| Car | MONTHS | MONTHS |
| Car | EXTRAHOURS | EXTRA HOURS |
| Car | EXTRADAYS | EXTRA DAYS |
| Car | EXTRAWEEKS | EXTRA WEEKS |
| Car | MILEAGEFEE | MILEAGE FEE |
| Car | UPGRADEFEE | UPGRADE FEE |
| Car | ADJUSTMENT | ADJUSTMENT |
| Car | DISCOUNT | DISCOUNT |
| Car | COLLECTION | COLLECTION |
| Car | DELIVERY | DELIVERY |
| Car | INTERCITY | INTERCITY |
| Car | ADDLDRIVER | ADDITIONAL DRIVER |
| Car | SERVICECHARGE | SERVICE CHARGE |
| Car | LDWCDW | LDW/CDW |
| Car | ALIAMOUNT | ALI AMOUNT |
| Car | PAIPECAMOUNT | PAI/PEC AMOUNT |
| Car | THEFTPROTECT | THEFT PROTECTION |
| Car | FUELSERVICE | FUEL SERVICE |
| Car | AIRPORTFEE | AIRPORT FEE |
| Car | AGEDIFFER | AGE DIFFERENTIAL |
| Car | CHILDSEAT | CHILD SEAT |
| Car | SKIRACK | SKI RACK |
| Car | ADDLSERVICE | ADDITIONAL SERVICE |
| Car | OTHERCHARGES | OTHER CHARGES |
| Car | TRANSACTIONFEE | TRANSACTION FEE |
| Car | SATELLITERADIO | SATELLITE RADIO |
| Car | NEVERLOST | NEVERLOST |
| Car | ACSURCHARGE | A/C SURCHARGE |
| Car | RESERVATIONFEE | RESERVATION FEE |
| Car | TAXDIFFER | TAX DIFFERENTIAL |
| Car | VOUCHERADJUST | VOUCHER ADJUSTMENT |
| Car | VATAMOUNT | VAT AMOUNT |
| Car | GSTAMOUNT | GST AMOUNT |
| Car | VEHICLELICENSE | VEHICLE LICENSE FEE |
| Car | CUSTFACILITY | CUSTOMER FACILITY |
| Car | VEHLEASETAX | MOTOR VEHICLE LEASE TAX |
| Car | ROADTAX | ROAD TAX |
| Car | OTHER | OTHER |
| Car | ACRECOVERYFEE | AIR CONDITION RECOVERY FEE |
| Car | CONCESSIONFEE | CONCESSION PASS THRU FEE |
| Car | CUSTRELATIONS | CUSTOMER RELATIONS EXPENSE |
| Car | TFFCORPVRT | TFFC OR PVRT |
| Car | IMPOUNDSTORAGE | IMPOUND/STORAGE |
| Car | LISAMOUNT | LIS AMOUNT |
| Car | SUPLIABILITY | SUPPLEMENTAL LIABILITY PROTECTION |
| Car | DROPOFFFEE | DROPOFF FEE |
| Car | WEEKEND | WEEKEND DAILY RATE |
| Air | OTHER | Miscellaneous charge |
| Air | SEGFEE | Segment fee |
| Air | SEGFEE_AS_FEE | Segment fees as fee |
| Air | SEGFEE_AS_FARE | Segment fees as base fare |
| Air | SEGFEE_AS_TAX | Segment fee as tax |
| Air | WIRELESS_FEE | Wireless Fee |
| Rail | OTHER | Miscellaneous charge |
| Rail | TICKET | Price of ticket |
| Rail | SEAT | Price of seat |
Time Zones
SAP Concur converts local date/time to UTC. In order to do that we need to be able to determine where the local time is.
Olson Time Zones
- Best practice is providing TimeZone (Olson or Windows time zone format) in addition to the required StartDateLocal and EndDateLocal.
- If you cannot provide TimeZone (Olson or Windows time zone format), SAP Concur recommends StartDateUtc and EndDateUtc in addition to the required StartDateLocal and EndDateLocal.
- Least preferable is providing StartCityCode in addition to the required StartDateLocal and EndDateLocal, if you cannot provide TimeZone or StartDateUtc and EndDateUtc.
| Africa/Cairo | Africa/Casablanca | Africa/Harare | Africa/Luanda |
| Africa/Nairobi | Africa/Windhoek | America/Anchorage | America/Argentina/Buenos_Aires |
| America/Asuncion | America/Bahia | America/Bogota | America/Buenos_Aires |
| America/Caracas | America/Chicago | America/Chihuahua | America/Denver |
| America/Godthab | America/Guyana | America/Halifax | America/Indianapolis |
| America/Los_Angeles | America/Manaus | America/Mexico_City | America/Montevideo |
| America/New_York | America/Phoenix | America/Regina | America/Santiago |
| America/Sao_Paulo | America/St_Johns | America/Swift_Current | America/Tijuana |
| Asia/Almaty | Asia/Amman | Asia/Baghdad | Asia/Baku |
| Asia/Bangkok | Asia/Beirut | Asia/Calcutta | Asia/Colombo |
| Asia/Damascus | Asia/Dhaka | Asia/Irkutsk | Asia/Jerusalem |
| Asia/Kabul | Asia/Kamchatka | Asia/Karachi | Asia/Karachi |
| Asia/Katmandu | Asia/Krasnoyarsk | Asia/Magadan | Asia/Muscat |
| Asia/Novosibirsk | Asia/Rangoon | Asia/Riyadh | Asia/Seoul |
| Asia/Shanghai | Asia/Singapore | Asia/Taipei | Asia/Tbilisi |
| Asia/Tehran | Asia/Tokyo | Asia/Ulaanbaatar | Asia/Vladivostok |
| Asia/Yakutsk | Asia/Yekaterinburg | Asia/Yerevan | Atlantic/Azores |
| Atlantic/Cape_Verde | Atlantic/South_Georgia | Australia/Adelaide | Australia/Brisbane |
| Australia/Darwin | Australia/Hobart | Australia/Perth | Australia/Sydney |
| Etc/GMT+12 | Etc/GMT-11 | Etc/GMT-2 | Europe/Athens |
| Europe/Berlin | Europe/Helsinki | Europe/Istanbul | Europe/Kaliningrad |
| Europe/London | Europe/Minsk | Europe/Moscow | Europe/Paris |
| Europe/Prague | Europe/Sarajevo | GMT | GMT-1200 |
| Indian/Mauritius | Pacific/Apia | Pacific/Auckland | Pacific/Fiji |
| Pacific/Guadalcanal | Pacific/Guam | Pacific/Honolulu | Pacific/Tongatapu |
| UTC |
Windows Time Zones
| Africa/Cairo | Africa/Casablanca | Africa/Harare | Africa/Luanda |
| Africa/Nairobi | Africa/Windhoek | America/Anchorage | America/Argentina/Buenos_Aires |
| America/Asuncion | America/Bahia | America/Bogota | America/Buenos_Aires |
| America/Caracas | America/Chicago | America/Chihuahua | America/Denver |
| America/Godthab | America/Guyana | America/Halifax | America/Indianapolis |
| America/Los_Angeles | America/Manaus | America/Mexico_City | America/Montevideo |
| America/New_York | America/Phoenix | America/Regina | America/Santiago |
| America/Sao_Paulo | America/St_Johns | America/Swift_Current | America/Tijuana |
| Asia/Almaty | Asia/Amman | Asia/Baghdad | Asia/Baku |
| Asia/Bangkok | Asia/Beirut | Asia/Calcutta | Asia/Colombo |
| Asia/Damascus | Asia/Dhaka | Asia/Irkutsk | Asia/Jerusalem |
| Asia/Kabul | Asia/Kamchatka | Asia/Karachi | Asia/Karachi |
| Asia/Katmandu | Asia/Krasnoyarsk | Asia/Magadan | Asia/Muscat |
| Asia/Novosibirsk | Asia/Rangoon | Asia/Riyadh | Asia/Seoul |
| Asia/Shanghai | Asia/Singapore | Asia/Taipei | Asia/Tbilisi |
| Asia/Tehran | Asia/Tokyo | Asia/Ulaanbaatar | Asia/Vladivostok |
| Asia/Yakutsk | Asia/Yekaterinburg | Asia/Yerevan | Atlantic/Azores |
| Atlantic/Cape_Verde | Atlantic/South_Georgia | Australia/Adelaide | Australia/Brisbane |
| Australia/Darwin | Australia/Hobart | Australia/Perth | Australia/Sydney |
| Etc/GMT+12 | Etc/GMT-11 | Etc/GMT-2 | Europe/Athens |
| Europe/Berlin | Europe/Helsinki | Europe/Istanbul | Europe/Kaliningrad |
| Europe/London | Europe/Minsk | Europe/Moscow | Europe/Paris |
| Europe/Prague | Europe/Sarajevo | GMT | GMT-1200 |
| Indian/Mauritius | Pacific/Apia | Pacific/Auckland | Pacific/Fiji |
| Pacific/Guadalcanal | Pacific/Guam | Pacific/Honolulu | Pacific/Tongatapu |
| UTC |
Itinerary v4
Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.
- Overview
- Process Flow
- Products and Editions
- Scope Usage
- Dependencies
- Access Token Usage
- Retrieve a Trip Record
- Schemas
Overview
The Itinerary API provides clients and authorized partners access to travel itinerary data.
Limitations: This API is only available to clients and partners who have been granted access by SAP Concur. Access to this documentation does not provide access to the API. This API is only available in US and EMEA data centers.
Prior Versions
- Itinerary v1 documentation is available here.
Process Flow

Products and Editions
- Concur Travel Professional Edition
- Concur Travel Standard Edition
Scope Usage
| Name | Description | Endpoint |
|---|---|---|
travel.itinerary.read |
Allows user to read travel itinerary data. | GET |
Dependencies
None.
Access Token Usage
This API supports only company level access tokens.
Retrieve a Trip Record
Retrieves the record of a trip.
Scopes
travel.itinerary.read - Refer to Scope Usage for full details.
Request
URI
Template
GET https://{region}.api.concursolutions.com/travel/v4/trips/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
region |
string |
- | Required: Region of the trip. Supported values: us, eu |
id |
string |
- | Required The trip ID. |
Headers
Response
Error Codes
Payload
Example
Request
GET https://us.api.concursolutions.com/travel/v4/trips/51519e89-2c1d-47ec-bd93-7c4ace9c57e6
Accept: application/json
Authorization: Bearer <JWT Token>
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"BookedVia": "Agent",
"Bookings": [
{
"AgencyName": "Outtask Travel Apollo",
"AgencyPCC": "C4I",
"AirfareQuotes": [
{
"BaseFare": 1264,
"BaseFareCurrency": "EUR",
"DateCreatedUtc": "2020-11-04T20:54:19.000+00:00",
"DateModifiedUtc": "2020-11-04T20:54:19.000+00:00",
"IssueByDate": "2020-09-25T15:54:18.000-00:00",
"TotalFare": 1341.2,
"TotalFareCurrency": "EUR"
}
],
"AirlineTickets": {
"AirlineAdjustment": [
{
"AddCollectAmount": 0,
"AdjustmentDateTime": "2020-11-02T00:00:00.000-00:00",
"AdjustmentType": "C",
"AirlineCharges": {
"Fixed": [
{
"Amount": -23,
"Currency": "EUR",
"Description": "Ice cream with meal",
"IsPaid": true,
"IsPrimary": false
}
]
},
"DateCreatedUtc": "2020-11-04T20:54:19.000+00:00",
"DateModifiedUtc": "2020-11-04T20:54:19.000+00:00",
"PassengerName": "EschIII/BenDwayne",
"PlatingCarrierNumericCode": "638",
"PlatingControlNumber": "0522482769",
"RecordLocator": "A56053",
"Taxes": [
{
"TaxAmount": 5,
"TaxAuthority": "USA",
"TaxName": "Silly Air Adjustment Tax",
"TaxRate": 0.58,
"TaxType": "US"
},
{
"TaxAmount": -5,
"TaxAuthority": "USA",
"TaxName": "Silly Air Adjustment Tax",
"TaxRate": 0.58,
"TaxType": "AY"
},
{
"TaxAmount": -9,
"TaxAuthority": "USA",
"TaxName": "Silly Air Adjustment Tax",
"TaxRate": 0.58,
"TaxType": "XF"
}
],
"TotalAdjustment": -100,
"TotalAdjustmentCurrency": "USD"
}
],
"AirlineTicket": [
{
"AccountingLine": {
"AirlineCode": "AA",
"Comment": "VIxxxxxxxxxxxx1111",
"Commission": "10.00",
"Fare": "1168",
"FOPMethod": "CX",
"MCOType": "AC",
"Tax": "72.40",
"TranControlNbr": "0251207588"
},
"AirlineTicketCoupons": [
{
"ClassOfService": "E",
"CouponNumber": 1,
"CouponStatus": "USED",
"EndCityCode": "DEN",
"FlightNumber": "5894",
"RateCode": "CQ690",
"StartCityCode": "IAD",
"StartDateLocal": "2020-12-11T15:54:18.000-00:00",
"Vendor": "AA"
},
{
"ClassOfService": "E",
"CouponNumber": 2,
"CouponStatus": "OPEN",
"EndCityCode": "LAX",
"FlightNumber": "6617",
"RateCode": "CQ210",
"StartCityCode": "IAD",
"StartDateLocal": "2020-12-16T15:54:18.000-00:00",
"Vendor": "UA"
}
],
"AirlineTicketFareBreakups": [
{
"BaseFare": 275.55,
"Currency": "USD",
"EndCityCode": "SFO",
"IsRefundable": true,
"StartCityCode": "LAX",
"TotalFare": 355.55,
"Vendor": "AA"
}
],
"BaseFare": 1168,
"BaseFareCurrency": "USD",
"ComparisonFare": 1,
"ComparisonFareCurrency": "USD",
"DateCreatedUtc": "2020-11-04T20:54:19.000+00:00",
"DateModifiedUtc": "2020-11-04T20:54:19.000+00:00",
"Endorsements": "NOREF/NOEXCH. NO VALUE AFTER FIRST FLT DATE",
"IssueDateTime": "2020-11-03T00:00:00.000-00:00",
"IssuingIataAgencyNumber": 82494313,
"IssuingPseudoCity": "13H1",
"LinearFareConstructor": "THIS IS A LINEAR FARE CONSTRUCTOR IAD-LAX",
"PassengerName": "DoverRN MSN CNBC/Emil",
"PlatingCarrierNumericCode": "001",
"PlatingControlNumber": "0251207588",
"ProgramCarrierCode": "AA",
"ProgramMembershipNumber": "387519635",
"RecordLocator": "A88372",
"Taxes": [
{
"TaxAmount": 58.4,
"TaxAuthority": "USA",
"TaxName": "Silly Air Ticket Tax",
"TaxRate": 0.57,
"TaxType": "US"
},
{
"TaxAmount": 5,
"TaxAuthority": "USA",
"TaxName": "SillyAir Ticket Tax",
"TaxRate": 0.57,
"TaxType": "AY"
},
{
"TaxAmount": 9,
"TaxAuthority": "USA",
"TaxName": "Silly Air Ticket Tax",
"TaxRate": 0.57,
"TaxType": "XF"
},
{
"TaxAmount": 3.6,
"TaxAuthority": "USA",
"TaxName": "Silly Air Ticket Tax",
"TaxRate": 0.57,
"TaxType": "ZP"
}
],
"Ticketless": false,
"TotalFare": 1244,
"TotalFareCurrency": "USD"
},
{
"AccountingLine": {
"AirlineCode": "AA",
"Comment": "VIxxxxxxxxxxxx1111",
"Commission": "10.00",
"Fare": "2341",
"FOPMethod": "CX",
"MCOType": "AC",
"Tax": "131.05",
"TranControlNbr": "0137973356"
},
"AirlineTicketCoupons": [
{
"ClassOfService": "E",
"CouponNumber": 1,
"CouponStatus": "EXCH",
"EndCityCode": "DEN",
"FlightNumber": "5894",
"RateCode": "CQ690",
"StartCityCode": "IAD",
"StartDateLocal": "2020-12-11T15:54:18.000-00:00",
"Vendor": "AA"
},
{
"ClassOfService": "E",
"CouponNumber": 2,
"CouponStatus": "EXCH",
"EndCityCode": "LAX",
"FlightNumber": "6617",
"RateCode": "CQ210",
"StartCityCode": "IAD",
"StartDateLocal": "2020-12-16T15:54:18.000-00:00",
"Vendor": "UA"
}
],
"AirlineTicketExchanges": [
{
"Amount": 100,
"AppliedSegment1": 1,
"AppliedSegment2": 1,
"Currency": "EUR",
"DateModifiedUtc": "2020-11-04T20:54:19.000+00:00",
"OldRecordLocator": "DEL324",
"PlatingCarrierNumericCode": "001",
"PlatingControlNumber": "0137973356"
}
],
"AirlineTicketFareBreakups": [
{
"BaseFare": 255.55,
"Currency": "USD",
"EndCityCode": "SFO",
"IsRefundable": true,
"StartCityCode": "JFK",
"TotalFare": 375.55,
"Vendor": "AA"
}
],
"BaseFare": 2341,
"BaseFareCurrency": "USD",
"ComparisonFare": 1,
"ComparisonFareCurrency": "USD",
"DateCreatedUtc": "2020-11-04T20:54:19.000+00:00",
"DateModifiedUtc": "2020-11-04T20:54:19.000+00:00",
"Endorsements": "NOREF/NOEXCH. NO VALUE AFTER FIRST FLT DATE",
"IssueDateTime": "2020-11-02T00:00:00.000-00:00",
"IssuingIataAgencyNumber": 96085218,
"IssuingPseudoCity": "13H1",
"LinearFareConstructor": "THIS IS A LINEAR FARE CONSTRUCTOR IAD-LAX",
"PassengerName": "DoverRN MSN CNBC/Emil",
"PlatingCarrierNumericCode": "001",
"PlatingControlNumber": "0137973356",
"ProgramCarrierCode": "AA",
"ProgramMembershipNumber": "387519635",
"RecordLocator": "A21012",
"Taxes": [
{
"TaxAmount": 117.05,
"TaxAuthority": "USA",
"TaxName": "Silly Air Ticket Tax",
"TaxRate": 0.57,
"TaxType": "US"
},
{
"TaxAmount": 5,
"TaxAuthority": "USA",
"TaxName": "SillyAir Ticket Tax",
"TaxRate": 0.57,
"TaxType": "AY"
},
{
"TaxAmount": 9,
"TaxAuthority": "USA",
"TaxName": "Silly Air Ticket Tax",
"TaxRate": 0.57,
"TaxType": "XF"
},
{
"TaxAmount": 3.6,
"TaxAuthority": "USA",
"TaxName": "Silly Air Ticket Tax",
"TaxRate": 0.57,
"TaxType": "ZP"
}
],
"Ticketless": false,
"TotalFare": 2475.65,
"TotalFareCurrency": "USD"
}
]
},
"BookingOwner": "ConcurTravel",
"BookingSource": "Manual",
"Charges": {
"Fixed": [
{
"Amount": 2,
"Currency": "USD",
"Description": "Booking fee",
"IsPrimary": false,
"SemanticsCode": "OTHER",
"SemanticsVendorType": "C",
"Vendor": "LH",
"VendorChargeCode": "BF2000"
}
],
"Percent": [
{
"Amount": 7,
"Currency": "USD",
"Description": "Tax",
"IsPrimary": false,
"SemanticsCode": "VAT",
"SemanticsVendorType": "H",
"VendorChargeCode": "Mars tax"
}
]
},
"DateBookedLocal": "2020-10-30T15:54:18.000-00:00",
"DateCreatedUtc": "2020-11-04T20:54:19.000+00:00",
"DateModifiedUtc": "2020-11-04T20:54:19.000+00:00",
"Delivery": {
"AddressLine1": "200 Street 1",
"AddressLine2": "Street 2",
"City": "London",
"Country": "UK",
"Email": "pasenger@keto.com",
"Latitude": 51.320000,
"LocationAdditionalDetails": "<Kiosk KioskLocation=\"On concourse\"/>",
"LocationDesc": "You will find the Self-service Ticket machine located at the front of the station. Aberystwyth Station is open 24 hours a day.",
"LocationName": "London Euston",
"Longitude": 0.500000,
"PhoneNumber": "(703)837.6100",
"ReferenceNumber": "RBK9G589",
"State": "MA",
"Type": "Kiosk",
"Zip": "32432"
},
"FormOfPaymentName": "CorporateAccount",
"FormOfPaymentType": "CA",
"IsGhostCard": false,
"PassPrograms": [
{
"Amount": 2,
"Name": "North America - Tango Plus 200 credits",
"Type": "Credits",
"UserFirstName": "Peter",
"UserLastName": "Neagle"
}
],
"Passengers": [
{
"FirstNameNumber": 0,
"FrequentTravelerPrograms": {
"FrequentFlyer": [
{
"FrequentFlyerNumber": "1234567890"
},
{
"AirlineVendor": "BA",
"FrequentFlyerNumber": "01234567890"
}
]
},
"LastNameNumber": 1,
"NameFirst": "Emil",
"NameLast": "Dover",
"NameSuffix": "RN MSN CNBC",
"NameTitle": "Mr.",
"TextName": "DoverRN MSN CNBC/Emil"
},
{
"FirstNameNumber": 1,
"FrequentTravelerPrograms": {
"FrequentFlyer": [
{
"FrequentFlyerNumber": "1234567890"
},
{
"AirlineVendor": "BA",
"FrequentFlyerNumber": "01234567890"
},
{
"FrequentFlyerNumber": "ABC12345",
"Status": "Gold",
"StatusExpirationDate": "2020-12-31T00:00:00.000-00:00"
}
]
},
"LastNameNumber": 1,
"NameFirst": "Ben",
"NameLast": "Esch",
"NameMiddle": "Dwayne",
"NameRemark": "FINANCE",
"NameSuffix": "III",
"NameTitle": "Mr.",
"TextName": "EschIII/BenDwayne"
}
],
"PhoneNumbers": [
{
"Description": "Residence",
"PassengerRPH": 0,
"PhoneNumber": "703-837-6100"
}
],
"RecordLocator": "BCC52120201104205418831",
"Remarks": {
"TripLinkRemarks": [
{
"TripLinkRemark": [
{
"Text": "TESTING"
}
]
}
]
},
"Segments": {
"Air": [
{
"AircraftCode": "767",
"Cabin": "E",
"CarbonEmissionLbs": 5470,
"CarbonModel": 158,
"CheckedBaggage": "Extra bag $25",
"ClassOfService": "E",
"ConfirmationNumber": "N1985820201104205418865",
"DateCreatedUtc": "2020-11-04T20:54:19.000+00:00",
"DateModifiedUtc": "2020-11-04T20:54:19.000+00:00",
"Duration": 140,
"EndCityCode": "DEN",
"EndDateLocal": "2020-12-11T18:14:18.000-00:00",
"EndDateUtc": "2020-12-12T01:14:18.000+00:00",
"EndGate": "68",
"EndTerminal": "D",
"FlightNumber": "5894",
"FrequentTravelerId": "387519635",
"IsUpgradeAllowed": true,
"LegId": 1,
"Meals": "Kebabs",
"Miles": 986,
"NumStops": 0,
"OperatedByFlightNumber": "8606",
"OperatedByVendor": "DL",
"OperatedByVendorName": "Delta",
"Seats": [
{
"PassengerRph": 0,
"SeatNumber": "12A",
"Status": "X"
},
{
"PassengerRph": 1,
"SeatNumber": "13B"
}
],
"SpecialInstructions": "Nothing special",
"StartCityCode": "IAD",
"StartDateLocal": "2020-12-11T15:54:18.000-00:00",
"StartDateUtc": "2020-12-11T20:54:18.000+00:00",
"StartGate": "47",
"StartTerminal": "A",
"Status": "HK",
"UpgradedDateTime": "2020-12-11T15:54:18.000-00:00",
"Vendor": "AA",
"VendorName": "American Airlines"
},
{
"AircraftCode": "767",
"Cabin": "E",
"CheckedBaggage": "Extra bag $25",
"ClassOfService": "E",
"ConfirmationNumber": "N7192620201104205418868",
"DateCreatedUtc": "2020-11-04T20:54:19.000+00:00",
"DateModifiedUtc": "2020-11-04T20:54:19.000+00:00",
"Duration": 81,
"EndCityCode": "LAX",
"EndDateLocal": "2020-12-16T17:15:18.000-00:00",
"EndDateUtc": "2020-12-17T01:15:18.000+00:00",
"EndGate": "20",
"EndTerminal": "D",
"FlightNumber": "6617",
"FrequentTravelerId": "1815857656",
"IsUpgradeAllowed": true,
"LegId": 2,
"Meals": "Kebabs",
"Miles": 663,
"NumStops": 2,
"OperatedByFlightNumber": "4047",
"OperatedByVendor": "UA",
"OperatedByVendorName": "United",
"Seats": [
{
"PassengerRph": 0,
"SeatNumber": "12A",
"Status": "X"
},
{
"PassengerRph": 1,
"SeatNumber": "13B"
}
],
"SpecialInstructions": "Nothing special",
"StartCityCode": "IAD",
"StartDateLocal": "2020-12-16T15:54:18.000-00:00",
"StartDateUtc": "2020-12-16T20:54:18.000+00:00",
"StartGate": "86",
"StartTerminal": "A",
"Status": "HK",
"UpgradedDateTime": "2020-12-11T15:54:18.000-00:00",
"Vendor": "UA",
"VendorName": "United"
}
]
},
"WebAddresses": [
{
"Description": "Work Email",
"Format": "E",
"PassengerRPH": 0,
"Type": "WRK",
"WebAddress": "Michaell@concur.com"
}
]
},
{
"AgencyName": "Outtask Travel Apollo",
"AgencyPCC": "C4I",
"BookingOwner": "ConcurTravel",
"BookingSource": "Manual",
"Charges": {
"Fixed": [
{
"Amount": 4,
"Currency": "USD",
"Description": "Booking fee",
"IsPrimary": false,
"SemanticsCode": "OTHER",
"SemanticsVendorType": "C",
"Vendor": "LH",
"VendorChargeCode": "BF2000"
}
],
"Percent": [
{
"Amount": 1,
"Currency": "USD",
"Description": "Tax",
"IsPrimary": false,
"SemanticsCode": "VAT",
"SemanticsVendorType": "H",
"VendorChargeCode": "Mars tax"
}
]
},
"DateBookedLocal": "2020-10-30T15:54:18.000-00:00",
"DateCreatedUtc": "2020-11-04T20:54:19.000+00:00",
"DateModifiedUtc": "2020-11-04T20:54:19.000+00:00",
"Delivery": {
"AddressLine1": "200 Street 1",
"AddressLine2": "Street 2",
"City": "London",
"Country": "UK",
"Email": "pasenger@keto.com",
"Latitude": 51.320000,
"LocationAdditionalDetails": "<Kiosk KioskLocation=\"On concourse\"/>",
"LocationDesc": "You will find the Self-service Ticket machine located at the front of the station. Aberystwyth Station is open 24 hours a day.",
"LocationName": "London Euston",
"Longitude": 0.500000,
"PhoneNumber": "(703)837.6100",
"ReferenceNumber": "RBK9G589",
"State": "MA",
"Type": "Kiosk",
"Zip": "32432"
},
"FormOfPaymentName": "CorporateAccount",
"FormOfPaymentType": "CA",
"PassPrograms": [
{
"Amount": 2,
"Name": "North America - Tango Plus 200 credits",
"Type": "Credits",
"UserFirstName": "Peter",
"UserLastName": "Neagle"
}
],
"Passengers": [
{
"FirstNameNumber": 0,
"LastNameNumber": 0,
"NameFirst": "Ann",
"NameLast": "Esch",
"NamePrefix": "Sgt.",
"NameRemark": "ABC*123",
"NameSuffix": "III",
"NameTitle": "Mr.",
"TextName": "EschIII/AnnSgt."
}
],
"PhoneNumbers": [
{
"Description": "Agency",
"PhoneNumber": "703-837-6106",
"Type": "W"
}
],
"RecordLocator": "K5589420201104205418911",
"Segments": {},
"WebAddresses": [
{
"Description": "Work Email",
"Format": "E",
"PassengerRPH": 0,
"Type": "WRK",
"WebAddress": "Michaell@concur.com"
}
]
},
{
"AgencyName": "Outtask Travel Apollo",
"AgencyPCC": "C4I",
"BookingOwner": "ConcurTravel",
"BookingSource": "Manual",
"Charges": {
"Fixed": [
{
"Amount": 4,
"Currency": "USD",
"Description": "Booking fee",
"IsPrimary": false,
"SemanticsCode": "OTHER",
"SemanticsVendorType": "C",
"Vendor": "LH",
"VendorChargeCode": "BF2000"
}
],
"Percent": [
{
"Amount": 3,
"Currency": "USD",
"Description": "Tax",
"IsPrimary": false,
"SemanticsCode": "VAT",
"SemanticsVendorType": "H",
"VendorChargeCode": "Mars tax"
}
]
},
"DateBookedLocal": "2020-10-30T15:54:18.000-00:00",
"DateCreatedUtc": "2020-11-04T20:54:19.000+00:00",
"DateModifiedUtc": "2020-11-04T20:54:19.000+00:00",
"Delivery": {
"AddressLine1": "200 Street 1",
"AddressLine2": "Street 2",
"City": "London",
"Country": "UK",
"Email": "pasenger@keto.com",
"Latitude": 51.320000,
"LocationAdditionalDetails": "<Kiosk KioskLocation=\"On concourse\"/>",
"LocationDesc": "You will find the Self-service Ticket machine located at the front of the station. Aberystwyth Station is open 24 hours a day.",
"LocationName": "London Euston",
"Longitude": 0.500000,
"PhoneNumber": "(703)837.6100",
"ReferenceNumber": "RBK9G589",
"State": "MA",
"Type": "Kiosk",
"Zip": "32432"
},
"FormOfPaymentName": "CorporateAccount",
"FormOfPaymentType": "CA",
"PassPrograms": [
{
"Amount": 2,
"Name": "North America - Tango Plus 200 credits",
"Type": "Credits",
"UserFirstName": "Peter",
"UserLastName": "Neagle"
}
],
"Passengers": [
{
"FirstNameNumber": 1,
"LastNameNumber": 0,
"NameFirst": "Ann",
"NameLast": "Dover",
"NamePrefix": "Sgt.",
"NameRemark": "FINANCE",
"NameTitle": "Mr.",
"TextName": "Dover/AnnSgt."
}
],
"PhoneNumbers": [
{
"Description": "Business",
"PhoneNumber": "800 401 8412",
"Type": "B"
}
],
"RecordLocator": "TF630420201104205418911",
"Remarks": {
"TripLinkRemarks": [
{
"TripLinkRemark": [
{
"Text": "MID OFFICE STUFF"
},
{
"Text": "TESTING"
},
{
"Text": "TO TEST THE MID OFFICE REMARKS"
}
]
}
]
},
"Segments": {
"Ride": [
{
"CancellationPolicy": "Call 20 minutes in advance to avoid charge",
"ConfirmationNumber": "C74450820201104205418911",
"Currency": "USD",
"DateCreatedUtc": "2020-11-04T20:54:19.000+00:00",
"DateModifiedUtc": "2020-11-04T20:54:19.000+00:00",
"DropoffInstructions": "Open door and jump out when speed is below 10 MPH",
"Duration": 2,
"EndAddress": "DCA",
"EndAddress2": "Thomas Ave & Abingon",
"EndCity": "Alexandria",
"EndCityCode": "DCA",
"EndCountry": "US",
"EndDateLocal": "2020-12-16T13:54:18.000-00:00",
"EndDateUtc": "2020-12-16T18:54:18.000+00:00",
"EndLatitude": 38.852843,
"EndLongitude": -77.038536,
"EndPostalCode": "22202",
"EndState": "VA",
"MeetingInstructions": "Meet by hot dog stand in front of building",
"Miles": 10,
"Name": "Yellow Cab",
"NumPersons": 2,
"NumberOfHours": 0.03333333333333333,
"PhoneNumber": "703-837-6100",
"PickupInstructions": "Pickup at given address",
"Rate": 24,
"RateDescription": "Hourly rate",
"RateType": "H",
"StartAddress": "209 Madison Street",
"StartCity": "Alexandria",
"StartCityCode": "DCA",
"StartCountry": "US",
"StartDateLocal": "2020-12-16T11:54:18.000-00:00",
"StartDateUtc": "2020-12-16T16:54:18.000+00:00",
"StartLatitude": 38.814098,
"StartLongitude": -77.040939,
"StartPostalCode": "22314",
"StartState": "VA",
"TimeZoneId": 25,
"Vendor": "$R",
"VendorName": "RideCharge"
}
]
},
"WebAddresses": [
{
"Description": "Home AIM",
"Format": "I",
"Type": "RES",
"WebAddress": "mloreOuttask"
}
]
}
],
"Comments": "Generated from - MakeRandomItineraryWithSpecifiedSegment: 401722883",
"CustomAttributes": [
{
"Data": "1914163392_1398750079_63698747",
"DataType": "Enumeration",
"DisplayOnItinerary": true,
"DisplayTitle": "Title_1882786037",
"Name": "Custom_1047320375"
},
{
"Data": "2144949539_499322633_1732005039",
"DataType": "Enumeration",
"DisplayOnItinerary": false,
"DisplayTitle": "Title_559871572",
"Name": "Custom_1726736195"
},
{
"Data": "683267112_1599532776_1875679442",
"DataType": "Enumeration",
"DisplayOnItinerary": true,
"DisplayTitle": "Title_119690786",
"ExternalId": 1088610323,
"Name": "Custom_1899779539"
},
{
"Data": "56781286_861560873_80874171",
"DataType": "Enumeration",
"DisplayOnItinerary": true,
"DisplayTitle": "Title_390352466",
"Name": "Custom_1579191469"
},
{
"Data": "2067714888_1442184475_1016439405",
"DataType": "String",
"DisplayOnItinerary": true,
"DisplayTitle": "Title_1544667785",
"Name": "Custom_1166600630"
},
{
"Data": "351251522_246017323",
"DataType": "Numeric",
"DisplayOnItinerary": true,
"DisplayTitle": "Title_19093583",
"Name": "Custom_750631891"
},
{
"Data": "821749202_364197364_762362918",
"DataType": "Enumeration",
"DisplayOnItinerary": false,
"DisplayTitle": "Title_1467115321",
"ExternalId": 1986175686,
"Name": "Custom_2007441754"
},
{
"Data": "473097600_978534217",
"DataType": "Numeric",
"DisplayOnItinerary": true,
"DisplayTitle": "Title_1137473737",
"Name": "Custom_1832693806"
},
{
"Data": "1679301535_433494967_1252049254",
"DataType": "Enumeration",
"DisplayOnItinerary": true,
"DisplayTitle": "Title_15390255",
"Name": "Custom_1100573803"
}
],
"DateBookedLocal": "2020-10-30T15:54:18.000-00:00",
"DateCreatedUtc": "2020-11-04T20:54:19.000+00:00",
"DateModifiedUtc": "2020-11-04T20:54:51.026+00:00",
"Description": "Trip from somewhere to somewhere else 506643842",
"EndDateLocal": "2020-12-16T17:15:18.000-00:00",
"EndDateUtc": "2020-12-17T01:15:18.000+00:00",
"id": "https://us.api.concursolutions.com/travel/v4/trips/08d019f6-8c7e-5e96-bbf4-04726ac5def2",
"ItinLocator": "gWutRRSrKhRhhY9lx0GUfP1YhfAXDTBtYwFTA$pKU",
"ProjectName": "Big Project # 43534534",
"StartDateLocal": "2020-12-11T15:54:18.000-00:00",
"StartDateUtc": "2020-12-11T20:54:18.000+00:00",
"TravelRequestId": "TR98318081",
"TripName": "My Random Trip #266255879",
"TripStatus": 0,
"UserLoginId": "itintrips@coreprofiletesting.com"
}
Schemas
Main Itinerary Level Elements
| Name | Type | Format | Description |
|---|---|---|---|
BookedByFirstName |
string |
- | The first name of the person who booked the trip. |
BookedByLastName |
string |
- | The last name of the person who booked the trip. |
BookedVia |
string |
- | The booking method for the trip. |
Bookings |
array |
Booking Element |
A parent element that contains a Booking child element for each booking associated with this itinerary. |
CancelComments |
string |
- | The comments provided if the itinerary is cancelled. Maximum length: 256 characters |
ClientLocator |
string |
- | Represents the unique identifier of the trip in an external (non-SAP Concur) system. Maximum length: 32 characters |
Comments |
string |
- | Comments for this itinerary. Maximum length: 512 characters |
CustomAttributes |
array |
Custom Attribute Element |
A parent element that contains a CustomAttribute child element for all custom attributes configured for trip level that may or not may not have values set. |
DateBookedLocal |
dateTime |
YYYY-MM-DDThh:mm:ss |
The date the trip was booked, in the local time of the booking's location. |
DateCreatedUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The date that this trip was created, in UTC. |
DateModifiedUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The UTC date that this trip was last modified. |
Description |
string |
- | The trip description. Maximum length: 512 characters |
EndDateLocal |
dateTime |
YYYY-MM-DDThh:mm:ss |
The end date of the trip in the ending location’s timezone. |
EndDateUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The end date of the trip, in UTC. |
HasOpenBookingPassive |
boolean |
true/false |
The trip has TripLink passive segments. |
ID |
string |
- | The unique identifier for the itinerary, this is included in the event and is used for the callback to get details of the trip. |
IsPersonal |
boolean |
true/false |
If true, the booking is a personal trip. |
ItinLocator |
string |
- | The itinerary locator. This element is now deprecated and only supported for backward compatibility. |
ProjectName |
string |
- | The associated project name for the trip. Maximum length: 255 characters |
StartDateLocal |
dateTime |
YYYY-MM-DDThh:mm:ss |
The start date of the trip in the starting location’s timezone. |
StartDateUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The start date of the trip, in UTC. |
TravelRequestID |
string |
- | SAP Concur Travel Request ID. |
TripLinkLocator |
string |
- | SAP Concur TripLink ID. |
TripName |
string |
- | Name of the trip. Maximum length: 255 characters |
TripStatus |
string |
- | The status of the itinerary. Supported values: 0 - Confirmed, 1 - Ticketed by agent, 2 - Cancelled |
UserLoginID |
string |
- | The user's login to the SAP Concur system. |
Booking Element
| Name | Type | Format | Description |
|---|---|---|---|
AgencyName |
string |
- | The name of the agency. |
AgencyPCC |
string |
- | Pseudo city code for the agency. |
AirfareQuotes |
array |
Airfare Quotes Element |
List of stored airfare quotes. This parent element has a Quote child element for each airfare quote. The Quote parent element contains the Airfare Quotes Child Elements. |
AirlineTickets |
type |
Airline Ticket Child Element |
List of airline tickets. This parent element contains Airline Tickets Child Elements. |
BookingOwner |
string |
- | Indicates the tool that supplied the booking to Concur Travel. |
BookingSource |
string |
- | The name of the booking source for this booking. A booking source is a textual name the system uses to track where a booking took place. |
Charges |
type |
Charge Detail Element |
List of charges for this booking. |
DateBookedLocal |
dateTime |
YYYY-MM-DDThh:mm:ss |
The date the booking was created, in the local time of the booking's location. |
DateCreatedUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The date that this booking was created, in UTC. |
DateModifiedUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The UTC date that this booking was last modified. |
Delivery |
type |
Delivery Element |
The method this booking was delivered. |
FormOfPaymentName |
string |
- | The name of the form of payment for the booking. |
FormOfPaymentType |
string |
- | The type of the form of payment. |
IsGhostCard |
boolean |
true/false |
If true, the payment was made using a shared corporate credit card. |
ItinSourceName |
string |
TravelSupplier |
The itinerary source. |
LastTicketDateUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
UTC timestamp of the latest ticket. |
MiscChargeOrders |
array |
Misc Charge Order Element |
This parent element has a MiscellaneousChargeOrder child element for each included miscellaneous charge. The MiscellaneousChargeOrder parent element contains Miscellaneous Charge Order Child Elements. |
Passengers |
array |
Passenger Element |
Contains a Passenger child element for each included passenger. |
PassPrograms |
array |
Pass Program Element |
This parent element has Pass Program child elements for each pass program associated with the booking. |
PhoneNumbers |
array |
Phone Number Data Element |
List of phone numbers associated with this booking. This parent element has a PhoneNumberData child element for each phone number associated with the booking. The PhoneNumberData parent element has the following child elements: PassengerRPH, PhoneNumber, Type, and Description. |
RailPayments |
type |
[Rail Payment Child Element](#schema-rail-payment-base) |
List of rail payments associated with rail segments in this booking. It has the following child elements: RailPayment that represents the payment information for a rail booking and RailAdjustment for the amount adjusted for a rail booking. |
RecordLocator |
string |
- | The unique identifier for a booking. This is often six alphanumeric characters, but can have other formats depending on the booking source. |
Remarks |
type |
Remark Element |
Remarks on the booking. |
Segments |
type |
Segment Element |
List of segments in this booking. The child elements included in this element vary depending on whether a TMC, SAP Concur client, third-party developer, or TripLink supplier is requesting the itinerary details: For TMCs, clients, and third-party developers, the Segments element contains one or more Air, Car, Hotel, Dining, Ride, Rail, Parking, or Travel parent elements. For TripLink suppliers, the Segments element contains one or more Air, Car, Hotel, or Ride parent elements. |
TicketMailingAddress |
string |
- | The mailing address for the booked ticket, if available. |
TicketPickupLocation |
string |
- | The pick-up location for the booked ticket, if available. |
TicketPickupNumber |
string |
- | The confirmation number for the booked ticket, if available. |
WaitListSegments |
type |
Wait List Segment Element |
The segments that the traveler is waitlisted for this booking. |
Warning |
array |
Warning Element |
The warnings associated with the booking. |
WebAddresses |
array |
Web Address Element |
List of web addresses such as emails, pick-up URLs, and so on associated with this booking. |
Airfare Quotes Element
| Name | Type | Format | Description |
|---|---|---|---|
AirlineCharges |
array |
Charge Detail Element |
This parent element contains a Fixed and a Percent child element for each fixed charge and percent of fixed charge associated with this airfare quote. For information about these child elements, see the Fixed Elements table and the Percent Elements table. |
BaseFare |
decimal |
- | The base fare of the airfare quote. |
BaseFareCurrency |
string |
- | The 3-letter ISO 4217 currency code for the base fare. |
BaseFareNuc |
decimal |
- | The base fare in NUC. |
BaseFareNucCurrency |
string |
- | The 3-letter ISO 4217 currency code for the base fare in NUC. |
DateCreatedUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The date that this airfare quote was created, in UTC. |
DateModifiedUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The UTC date that this airfare quote was last modified. |
Endorsements |
string |
- | Notes from the airline if it endorses the ticket as acceptable on a different airline. |
IssueByDate |
dateTime |
YYYY-MM-DDThh:mm:ss |
The date the quote must be issued by. |
TotalFare |
decimal |
- | The total price of the booking. |
TotalFareCurrency |
string |
- | The 3-letter ISO 4217 currency code for the total fare. |
Airline Ticket Child Element
| Name | Type | Format | Description |
|---|---|---|---|
AirlineAdjustment |
array |
Airline Adjustment Element |
Any adjustment made to the booking. For information about the child elements of AirlineAdjustmentType, see the AirlineAdjustmentType Elements table. |
AirlineTicket |
array |
Airline Ticket Element |
The manual airline ticket for the booking. For information about the child elements of ManualAirlineTicket, see the ManualAirlineTicket Elements table. |
ManualAirlineTicket |
array |
Manual Airline Ticket Element |
The airline ticket for the booking. For information about the child elements of AirlineTicket, see the AirlineTicket Elements table. |
Delivery Element
| Name | Type | Format | Description |
|---|---|---|---|
AddressLine1 |
string |
- | The delivery street address. |
AddressLine2 |
string |
- | The delivery street address. |
City |
string |
- | The city of the delivery address. |
Country |
string |
- | The country of the delivery address. |
Email |
string |
- | The email of the delivery contact. |
Latitude |
decimal |
- | The latitude of the delivery address. |
LocationAdditionalDetails |
string |
- | Additional information about the delivery location. |
LocationDesc |
string |
- | The description of the delivery location. |
LocationName |
string |
- | The name of the delivery location. |
Longitude |
decimal |
- | The longitude of the delivery address. |
PhoneNumber |
string |
- | The phone number of the delivery contact. |
ReferenceNumber |
string |
- | The reference number for the delivery. |
State |
string |
- | The state of the delivery address. |
Type |
string |
- | The type of delivery address. |
Zip |
string |
- | The postal code or zip code of the delivery address. |
Miscellaneous Charge Order Element
| Name | Type | Format | Description |
|---|---|---|---|
DateCreatedUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The date the charge order was created, in UTC. |
DateModifiedUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The date the charge order was last modified, in UTC. |
IssueDate |
dateTime |
YYYY-MM-DDThh:mm:ss |
The date the charge order was issued. |
PlatingCarrierNumericCode |
string |
- | The three-digit ticket number that indicates the airline code. Examples: 001 - American, 005 - Continental, 006 - Delta, 012 - Northwest |
PlatingControlNumber |
string |
- | Ten digits of the ticket number that indicates the ticket control number. |
TotalAmount |
decimal |
- | The total amount of charge orders for the ticket. |
TotalAmountCurrency |
string |
- | The 3-letter ISO 4217 currency code for the total charge order amount. |
Pass Program Element
| Name | Type | Format | Description |
|---|---|---|---|
Amount |
decimal |
- | The program amount. |
Name |
string |
- | The program name. |
Type |
string |
- | The program type. |
UserFirstName |
string |
- | The first name of the passenger. |
UserLastName |
string |
- | The last name of the passenger. |
Passenger Element
| Name | Type | Format | Description |
|---|---|---|---|
City |
string |
- | The city of the passenger's address. |
Country |
string |
- | The country of the passenger's address. |
FirstNameNumber |
integer |
- | The number of characters in the passenger's first name. |
FrequentTravelerProgram |
type |
Frequent Traveler Program Element |
Passenger's loyalty programs. |
LastNameNumber |
number |
- | The number of characters in the passenger's last name. |
NameFirst |
string |
- | The first name of the passenger. |
NameLast |
string |
- | The last name of the passenger. |
NameMiddle |
string |
- | The middle name of the passenger. |
NamePrefix |
string |
- | The name prefix of the passenger. |
NameRemark |
string |
- | Additional details about the passenger's name. |
NameSuffix |
string |
- | The name suffix of the passenger. |
NameTitle |
string |
- | The title of the passenger. |
PostalCode |
string |
- | The postal code or zip code of the passenger's address. |
State |
string |
- | The state of the passenger's address. |
StreetAddress |
string |
- | The passenger's street address. |
StreetAddress2 |
string |
- | The passenger's street address. |
TextName |
string |
- | The user's full name as entered in the booking tool if different from the name in the database. |
Phone Number Data Element
| Name | Type | Format | Description |
|---|---|---|---|
Description |
string |
- | The description for the phone number. |
PassengerRPH |
integer |
- | Indicates the passenger to whom this phone number belongs. |
PhoneNumber |
string |
- | The passenger's phone number. |
Type |
string |
- | The type of phone number. |
Rail Payment Child Element
| Name | Type | Format | Description |
|---|---|---|---|
RailAdjustment |
array |
Rail Adjustment Element |
The amount adjusted for a rail booking. For information about the RailAdjustment child elements, see the Rail Adjustment Element table. |
RailPayment |
array |
Rail Payment Element |
The payment information for a rail booking. For information about the RailPayment child elements, see the Rail Payment Element table. |
Remark Element
| Name | Type | Format | Description |
|---|---|---|---|
TripLinkRemarks |
array |
TripLink Remarks Element |
TripLink remarks. |
TripLink Remarks Element
| Name | Type | Format | Description |
|---|---|---|---|
TripLinkRemark |
array |
TripLink Remark Element |
A TripLink remark. |
TripLink Remark Element
| Name | Type | Format | Description |
|---|---|---|---|
Text |
string |
- | TripLink remarks. |
Segment Element
| Name | Type | Format | Description |
|---|---|---|---|
Air |
array |
Air Segment Element |
Air segment. |
Car |
array |
Car Segment Element |
Car segment. |
Dining |
array |
Dining Segment Element |
Dining segment. |
Hotel |
array |
Hotel Segment Element |
Hotel segment. |
Parking |
array |
Parking Segment Element |
Parking segment. |
Rail |
array |
Rail Segment Element |
Rail segment. |
Ride |
array |
Ride Segment Element |
Ride segment. |
Travel |
array |
Travel Segment Element |
Travel segment. |
Wait List Segment Element
| Name | Type | Format | Description |
|---|---|---|---|
SegmentOption |
array |
Segment Option Item Element |
Air segments on which a user is waitlisted. |
Warning Element
| Name | Type | Format | Description |
|---|---|---|---|
Code |
array |
- | Warning code. |
Text |
array |
- | Warning text. |
Type |
array |
- | Warning type. |
Charge Detail Element
| Name | Type | Format | Description |
|---|---|---|---|
Fixed |
array |
Fixed Charge Element |
The fixed charges. |
Percent |
array |
Percent of Fixed Charges Element |
The percent of fixed charges. |
Rate |
array |
Rate Charge Element |
The rate for the booking. |
RateWithAllowance |
array |
Rate With Allowance Charge Element |
The rate for the booking, including any travel allowances. |
Airline Adjustment Element
| Name | Type | Format | Description |
|---|---|---|---|
AddCollectAmount |
decimal |
- | Specifies the net fare (i.e. the actual fare paid) if it differs from the total fare for the ticket due to applicable credits from the original exchanged ticket. |
AdjustmentDateTime |
dateTime |
YYYY-MM-DDThh:mm:ss |
Local timestamp for the adjustment. |
AdjustmentDateTimeUTC |
dateTime |
YYYY-MM-DDThh:mm:ss |
UTC timestamp for the adjustment. |
AdjustmentType |
string |
- | Type of adjustment. |
AirlineCharges |
array |
Charge Detail Element |
Charges associated to the adjustment. |
DateCreatedUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
UTC timestamp of adjustment creation. |
DateModifiedUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
UTC timestamp of adjustment modification. |
PassengerName |
string |
- | Name of passenger. |
PlatingCarrierNumericCode |
string |
- | The three-digit ticket number that indicates the airline code. Examples: 001 - American, 005 - Continental, 006 - Delta, 012 - Northwest |
PlatingControlNumber |
string |
- | Ten digits of the ticket number that indicates the ticket control number. |
RecordLocator |
string |
- | The unique identifier for a booking. This is often six alphanumeric characters, but can have other formats depending on the booking source. |
Taxes |
array |
Tax Element |
Taxes on the adjustment. |
TotalAdjustment |
decimal |
- | Total cost of adjustment. |
TotalAdjustmentCurrency |
string |
- | Currency of the adjustment. |
Airline Ticket Element
| Name | Type | Format | Description |
|---|---|---|---|
AccountingLine |
type |
Accounting Line Element |
The accounting line on the airline ticket. |
AddCollectAmount |
decimal |
- | Specifies the net fare (i.e. the actual fare paid) if it differs from the total fare for the ticket due to applicable credits from the original exchanged ticket. |
AirlineCharges |
array |
Charge Detail Element |
Charges associated to the ticket. |
AirlineTicketCoupons |
array |
Airline Ticket Coupon Element |
A list of coupons for this ticket. This parent element has an AirlineTicketCoupon child element for each coupon associated with this airline ticket. For information about these child elements, see the Airline Ticket Coupon Element table. |
AirlineTicketExchanges |
array |
Airline Ticket Exchanges Element |
A list of exchanges for this ticket. This parent element has an AirlineTicketExchange child element for each exchange associated with this airline ticket. For information about these child elements, see the Airline Ticket Exchange Element table. |
AirlineTicketFareBreakups |
array |
Airline Ticket Fare Breakups Element |
A list of fare breakups for this ticket. This parent element has an AirlineTicketFareBreakup child element for each fare breakup associated with this airline ticket. For information about these child elements, see the Airline Ticket Fare Breakup Element table. |
BaseFare |
decimal |
- | Fare without any tax penalties. |
BaseFareCurrency |
string |
- | The 3-letter ISO 4217 currency code for the base fare. |
BaseFareNuc |
decimal |
- | The base fare in NUC. |
BaseFareNucCurrency |
string |
- | The 3-letter ISO 4217 currency code for the base fare in NUC. |
ComparisonFare |
decimal |
- | A baseline fare provided by the TMC for contractual reference. |
ComparisonFareCurrency |
string |
- | The 3-letter ISO 4217 currency code for the comparison fare. |
DateCreatedUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
UTC timestamp of ticket creation. |
DateModifiedUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
UTC timestamp of ticket modification. |
Endorsements |
string |
- | Notes from the airline if it endorses the ticket as acceptable on a different airline. |
InvoiceNumber |
string |
- | Invoice associated with the ticket. |
IssueDateTime |
dateTime |
YYYY-MM-DDThh:mm:ss |
Timestamp of ticket issuing. |
IssueDateTimeUTC |
dateTime |
YYYY-MM-DDThh:mm:ss |
UTC timestamp of ticket issuing. |
IssuingIataAgencyNumber |
integer |
- | IATA number of agency that issued the ticket. |
IssuingPseudoCity |
string |
- | Pseudo city code of the issuing ticket agency. |
LinearFareConstructor |
string |
A breakdown of the total fare. | |
MasterTicketNumber |
string |
- | The ticket number. |
NameReference |
string |
- | Not used. |
PassengerName |
string |
- | Airline ticket holder's full name. |
PlatingCarrierNumericCode |
string |
- | The three-digit ticket number that indicates the airline code. Examples: 001 - American, 005 - Continental, 006 - Delta, 012 - Northwest |
PlatingControlNumber |
string |
- | Ten digits of the ticket number that indicates the ticket control number. |
ProgramCarrierCode |
string |
- | The airline vendor code for the program. |
ProgramMembershipNumber |
string |
- | The membership number for the program. |
RecordLocator |
string |
- | The unique identifier for a booking. This is often six alphanumeric characters, but can have other formats depending on the booking source. |
SabreDkNumber |
string |
- | Appears only if a booking was created by the relavent GDS. |
Taxes |
array |
Tax Element |
Taxes applied to the airline ticket. |
Ticketless |
boolean |
true/false |
If true, the ticket is ticketless. |
TicketType |
string |
- | The type of the ticket. |
TotalFare |
decimal |
- | Total cost of ticket. |
TotalFareCurrency |
string |
- | The 3-letter ISO 4217 currency code of ticket. |
TourIdentifier |
string |
- | Special negotiated fare. |
Manual Airline Ticket Element
| Name | Type | Format | Description |
|---|---|---|---|
AirlineCharges |
array |
Charge Detail Element |
Charges associated to the ticket. |
BaseFare |
decimal |
- | Fare without any tax penalties. |
BaseFareCurrency |
string |
- | The 3-letter ISO 4217 currency code for the base fare. |
DateCreatedUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
UTC timestamp of ticket creation. |
DateModifiedUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
UTC timestamp of ticket modification. |
Taxes |
array |
Tax Element |
Taxes on the ticket. |
TotalFare |
decimal |
- | Total cost of ticket. |
TotalFareCurrency |
string |
- | The 3-letter ISO 4217 currency code of ticket. |
Fixed Charge Element
| Name | Type | Format | Description |
|---|---|---|---|
Amount |
decimal |
- | The total amount for the rate for the booking. |
Currency |
string |
- | The 3-letter ISO 4217 currency code for the total amount. |
Description |
string |
- | The description for the rate. |
IsPaid |
boolean |
true/false |
If true, the rate has been paid. |
IsPrimary |
boolean |
true/false |
If true, the rate is the primary rate. If one of the rates is the actual rate and the rest are penalties, the actual rate should be set as IsPrimary. Only one charge in a set should be set as primary. |
SemanticsCode |
string |
- | Indicates the charge category for the line item. Refer to the Semantics Codes table for more information. |
SemanticsVendorType |
string |
- | The vendor type. Supported values: H - Hotel, C - Car, A - Air, G - Ground, R - Rail |
StartDateLocal |
dateTime |
YYYY-MM-DDThh:mm:ss |
The start date of the booking, in the user's local time. |
Vendor |
string |
- | The vendor for the booking charge. |
VendorChargeCode |
string |
- | The vendor's code for the charge. |
Percent of Fixed Charges Element
| Name | Type | Format | Description |
|---|---|---|---|
Amount |
decimal |
- | The total amount for the rate for the booking. |
Currency |
string |
- | The 3-letter ISO 4217 currency code for the total amount. |
Description |
string |
- | The description for the rate. |
IsPaid |
boolean |
true/false |
If true, the rate has been paid. |
IsPrimary |
boolean |
true/false |
If true, the rate is the primary rate. If one of the rates is the actual rate and the rest are penalties, the actual rate should be set as IsPrimary. Only one charge in a set should be set as primary. |
SemanticsCode |
string |
- | Indicates the charge category for the line item. Refer to the Semantics Codes table for more information. |
SemanticsVendorType |
string |
- | The vendor type. Supported values: H - Hotel, C - Car, A - Air, G - Ground, R - Rail |
StartDateLocal |
dateTime |
YYYY-MM-DDThh:mm:ss |
The start date of the booking, in the user's local time. |
Vendor |
string |
- | The vendor for the booking charge. |
VendorChargeCode |
string |
- | The vendor's code for the charge. |
Rate Charge Element
| Name | Type | Format | Description |
|---|---|---|---|
Amount |
decimal |
- | The total amount for the rate for the booking. |
Currency |
string |
- | The 3-letter ISO 4217 currency code for the total amount. |
Description |
string |
- | The description for the rate. |
IsPaid |
boolean |
true/false |
If true, the rate has been paid. |
IsPrimary |
boolean |
true/false |
If true, the rate is the primary rate. If one of the rates is the actual rate and the rest are penalties, the actual rate should be set as IsPrimary. Only one charge in a set should be set as primary. |
NumUnits |
decimal |
- | The number of units expected for the charge. |
PerUnit |
string |
- | The unit of measure for the charge. Example: DAY, WEEK, MONTH |
SemanticsCode |
string |
- | Indicates the charge category for the line item. Refer to the Semantics Codes table for more information. |
SemanticsVendorType |
string |
- | The vendor type. Supported values: H - Hotel, C - Car, A - Air, G - Ground, R - Rail |
StartDateLocal |
dateTime |
YYYY-MM-DDThh:mm:ss |
The start date of the booking, in the user's local time. |
Vendor |
string |
- | The vendor for the booking charge. |
VendorChargeCode |
string |
- | The vendor's code for the charge. |
Rate With Allowance Charge Element
| Name | Type | Format | Description |
|---|---|---|---|
AllowanceAmount |
decimal |
- | The cost of overage fees when the allowance is exceeded. For example, if the allowance is 5000 miles, the cost could be $0.02 per mile. The overage must be in the same currency as the basic rate. |
AllowanceIsUnlimited |
boolean |
true/false |
If true, the allowance is unlimited. |
AllowanceNumUnits |
decimal |
- | The number of units for the allowance associated with the charge. |
AllowanceUnit |
string |
- | The unit of measure for the allowance associated with the charge. |
Amount |
decimal |
- | The total amount for the rate for the booking. |
Currency |
string |
- | The 3-letter ISO 4217 currency code for the total amount. |
Description |
string |
- | The description for the rate. |
IsPaid |
boolean |
true/false |
If true, the rate has been paid. |
IsPrimary |
boolean |
true/false |
If true, the rate is the primary rate. If one of the rates is the actual rate and the rest are penalties, the actual rate should be set as IsPrimary. Only one charge in a set should be set as primary. |
NumUnits |
decimal |
- | The number of units expected for the charge. |
PerUnit |
string |
- | The unit of measure for the charge. Example: DAY, WEEK, MONTH |
SemanticsCode |
string |
- | Indicates the charge category for the line item. Refer to the Semantics Codes table for more information. |
SemanticsVendorType |
string |
- | The vendor type. Supported values: H - Hotel, C - Car, A - Air, G - Ground, R - Rail |
StartDateLocal |
dateTime |
YYYY-MM-DDThh:mm:ss |
The start date of the booking, in the user's local time. |
Vendor |
string |
- | The vendor for the booking charge. |
VendorChargeCode |
string |
- | The vendor's code for the charge. |
Rail Adjustment Element
| Name | Type | Format | Description |
|---|---|---|---|
AdjustmentDateTime |
dateTime |
YYYY-MM-DDThh:mm:ss |
Timestamp for the adjustment. |
AdjustmentDateTimeUTC |
dateTime |
YYYY-MM-DDThh:mm:ss |
UTC timestamp for the adjustment. |
AdjustmentType |
string |
- | Type of adjustment. |
DateCreatedUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
UTC timestamp for adjustment creation. |
DateModifiedUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
UTC timestamp for adjustment modification. |
RailCharges |
array |
Charge Detail Element |
List of charges for this rail booking. |
Taxes |
array |
Tax Element |
Taxes on the adjustment. |
TicketDocumentIdentifier |
string |
- | Not used. |
TotalAdjustment |
decimal |
- | Total cost of the adjustment. |
TotalAdjustmentCurrency |
string |
- | The 3-letter ISO 4217 currency code for the total adjustment. |
Rail Payment Element
| Name | Type | Format | Description |
|---|---|---|---|
BaseFare |
decimal |
- | Fare without any tax penalties. |
BaseFareCurrency |
string |
- | The 3-letter ISO 4217 currency code for the base fare. |
DateCreatedUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The date the quote was created, in UTC. |
DateModifiedUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The date the quote was last modified, in UTC. |
IncludesVAT |
boolean |
true/false |
If true, includes the value add tax. |
IssueByDate |
dateTime |
YYYY-MM-DDThh:mm:ss |
The date the quote must be issued by. |
IssueDateTime |
dateTime |
YYYY-MM-DDThh:mm:ss |
Timestamp of quote being issued. |
IssueDateTimeUTC |
dateTime |
YYYY-MM-DDThh:mm:ss |
UTC timestamp of quote being issued. |
RailCharges |
array |
Charge Detail Element |
List of charges for this rail booking. |
TaxInvoice |
boolean |
true/false |
If true, the charge is a legal tax invoice. |
Taxes |
array |
Tax Element | Taxes on the payment. |
TicketDocumentIdentifier |
string |
- | Not used. |
TicketType |
string |
- | Type of the ticket. |
TotalFare |
decimal |
- | The total price of the booking. |
TotalFareCurrency |
string |
- | The 3-letter ISO 4217 currency code for the total fare. |
VatApplicable |
boolean |
true/false |
If true, value add tax is applicable. |
Air Segment Element
| Name | Type | Format | Description |
|---|---|---|---|
AircraftCode |
string |
- | The code for the aircraft type. |
Bags |
string |
- | The number of bags included in the booking. |
Cabin |
string |
- | The section of the airplane for the booking. |
CancellationNumber |
string |
- | The cancellation number from the vendor. This field should be set when you cancel a segment. |
CancellationPolicy |
string |
- | The cancellation policy from the vendor. |
CarbonEmissionLbs |
decimal |
- | The pounds of carbon emission for this booking. |
CarbonModel |
integer |
- | The model used to calculate the carbon emissions. |
Charges |
type |
Charge Detail Element |
List of charges for this booking. |
CheckedBaggage |
string |
- | Whether the booking includes checked baggage. |
ClassOfService |
string |
- | The class of the booking. |
ConfirmationNumber |
string |
- | The record locator or confirmation number for the flight from the airline. |
DateCancelledUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The date the booking was cancelled, in UTC. |
DateCreatedUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The date the booking was created, in UTC. |
DateModifiedUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The date the booking was modified, in UTC. |
Duration |
integer |
- | The duration of the booked flight. |
EndCityCode |
string |
- | The IATA airport code for the end city of the booking. |
EndDateLocal |
dateTime |
YYYY-MM-DDThh:mm:ss |
The booking ending time and date, in the booking location's local time.For TripLink suppliers: The time portion of this value will be set to T00:00:00 if the request is from a TripLink - Open Booking Air supplier that does not own the booking. |
EndDateUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The booking ending time and date, in UTC. For TripLink suppliers: The time portion of this value will be set to T00:00:00 if the request is from a TripLink - Open Booking Air supplier that does not own the booking. |
EndGate |
string |
- | The arrival gate for the booking. For TripLink suppliers: Will not appear in the response if the request is from a TripLink - Open Booking Air supplier that does not own the booking. |
EndTerminal |
string |
- | The arrival terminal for the booking.For TripLink suppliers: Will not appear in the response if the request is from a TripLink - Open Booking Air supplier that does not own the booking. |
ETicket |
string |
E/Y/N |
Whether the booking has an e-ticket. |
FlightNumber |
string |
- | The flight number for the booking. |
FrequentTravelerId |
string |
- | The traveler’s ID for the frequent traveler reward program. |
IsOpenSegment |
boolean |
true/false |
If true, the segment is open. |
IsPreferredVendor |
boolean |
true/false |
If true, the airline is marked as a preferred property by the company. |
IsUpgradeAllowed |
boolean |
true/false |
If true, the booking can be upgraded. |
LegID |
string |
- | The leg ID of the booking. Leg IDs do not change on a connection. For each unique leg ID in the trip, all flights subsequent to the first segment with the same leg ID are connections. |
Meals |
string |
- | The meals included in the booking. |
Miles |
integer |
- | The number of miles included in the booking. |
Notes |
string |
- | Additional details about the booking. |
NumStops |
unsignedByte |
- | The number of stops in the booking. |
OpenSegment |
string |
- | Additional information about the open segment. |
OperatedByFlightNumber |
string |
- | Flight number provided by the airline operating the flight on behalf of the booked airline. |
OperatedByVendor |
string |
- | The airline operating the flight on behalf of the booked airline. |
OperatedByVendorName |
string |
- | The name of the airline operating the flight on behalf of the booked airline. |
Remarks |
type |
Remark Element |
Remarks on the segment. |
RuleViolations |
array |
Rule Violation Element |
The list of rule violations associated with the itinerary. This parent element contains a Rule Violation child element for each associated rule violation. |
Seats |
array |
Air Seat Element |
The seats for the booking. This parent element contains an AirSeat element for each included seat. For more information, see the Air Seat Elements table later on this page. |
Services |
string |
- | The services included in the booking. |
SpecialInstructions |
string |
- | Additional instructions regarding the booking. Maximum length: 256 |
StartCityCode |
string |
- | The IATA airport code for the starting address for the booking. |
StartDateLocal |
dateTime |
YYYY-MM-DDThh:mm:ss |
The booking starting time and date, in the booking location's local time. For TripLink suppliers: The time portion of this value will be set to T00:00:00 if the request is from a TripLink - Open Booking Air supplier that does not own the booking. |
StartDateUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The booking starting time and date, in UTC. For TripLink suppliers: The time portion of this value will be set to T00:00:00 if the request is from a TripLink - Open Booking Air supplier that does not own the booking. |
StartGate |
string |
- | The departure gate for the booking. For TripLink suppliers: Will not appear in the response if the request is from a TripLink - Open Booking Air supplier that does not own the booking. |
StartTerminal |
string |
- | The departure terminal for the booking. For TripLink suppliers: Will not appear in the response if the request is from a TripLink - Open Booking Air supplier that does not own the booking. |
Status |
string |
- | The GDS based booking status for the segment. Example: HK, HL, BK |
TimeZone |
string |
Olson or Windows Time Zones |
The time zone of the booking. |
TimeZoneID |
integer |
- | The ID for the time zone of the booking. |
UpgradedDateTime |
dateTime |
YYYY-MM-DDThh:mm:ss |
The date and time the booking was upgraded. |
Vendor |
string |
- | The two-letter GDS vendor code |
VendorFlags |
string |
- | Not used |
VendorName |
string |
- | The name of the vendor. |
Car Segment Element
| Name | Type | Format | Description |
|---|---|---|---|
AirCondition |
string |
- | The character code that indicates if car has air conditioner. Supported values: R - AC, N - No AC |
Body |
string |
- | The body style of the car. Supported values: B - Two-door sedan, D - Four-door sedan, F - Four-wheel drive, J - All terrain, K - Truck, L - Limo, P - Pickup, R - recreation, S - Sport, T - Convertible, V - Van, W - Wagon/Estate, X - Special |
CancellationNumber |
string |
- | The cancellation number from the vendor. This field should be set when you cancel a segment. |
Charges |
type |
Charge Detail Element |
List of charges for this booking. |
Class |
string |
- | Character code to indicate the class of the car. Varies by vendor. Supported values: C - Compact, E - Economy, F - Full size, I - Intermediate, L - Luxury, M - Mini, P - Premium, S - Standard, X - Special |
ConfirmationNumber |
string |
- | The confirmation number from the vendor. |
Currency |
string |
- | The 3-letter ISO 4217 currency code for the booking. |
DailyRate |
decimal |
- | The daily rate for the booking. |
DateCancelledUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The date the booking was cancelled, in UTC. |
DateCreatedUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The date the booking was created, in UTC. |
DateModifiedUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The date the booking was modified, in UTC. |
DiscountCode |
string |
- | The discount code used by the company or TMC to get a discounted rate. |
DropoffCollectionAddress1 |
string |
- | The AddressLine1 for the dropoff address when the rental service offers dropoff. |
DropoffCollectionAddressType |
string |
- | The type of address for the dropoff address when the rental service offers dropoff. |
DropoffCollectionCategory |
string |
- | The category of dropofff address when the rental service offers dropoff. |
DropoffCollectionCityCode |
string |
- | The IATA airport code for the dropoff address when the rental service offers dropoff. |
DropoffCollectionCity |
string |
- | City for the dropoff address when the rental service offers dropoff. |
DropoffCollectionCountry |
string |
- | The country for the dropoff address when the rental service offers dropoff. |
DropoffCollectionLatitude |
string |
- | The latitude for the dropoff address when the rental service offers dropoff. |
DropoffCollectionLongitude |
string |
- | The longitude for the dropoff address when the rental service offers dropoff. |
DropoffCollectionNumber |
string |
- | The number for the dropoff address when the rental service offers dropoff. |
DropoffCollectionPhoneNumber |
string |
- | The phone number for the dropoff address when the rental service offers dropoff. |
DropoffCollectionPostalCode |
string |
- | The postal code for the dropoff address when the rental service offers dropoff. |
DropoffCollectionState |
string |
- | The state for the dropoff address when the rental service offers dropoff. |
EndAddress2 |
string |
- | The ending address for the booking. |
EndAddress |
string |
- | The ending address for the booking. |
EndCityCode |
string |
- | The IATA airport code for the ending address for the booking. |
EndCity |
string |
- | The ending address for the booking. |
EndCloseTime |
string |
- | The closing time for the dropoff location. |
EndCountry |
string |
- | The ending address for the booking. |
EndDateLocal |
dateTime |
YYYY-MM-DDThh:mm:ss |
The booking ending time and date, in the booking location's local time. |
EndDateUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The booking ending time and date, in UTC. |
EndLatitude |
string |
- | The latitude for the ending location of the booking. |
EndLongitude |
string |
- | The longitude for the ending location of the booking. |
EndOpenTime |
string |
- | The opening time of the dropoff location. |
EndPhoneNumber |
string |
- | The phone number of the dropoff location. |
EndPostalCode |
string |
- | The ending address for the booking. |
EndState |
string |
- | The ending address for the booking. |
IsGhostCard |
boolean |
true/false |
Indicates if a payment was made using a shared corporate credit card. |
IsPreferredVendor |
integer |
- | If true, the rental service is marked as a preferred service by the company. |
IsUpgradeAllowed |
boolean |
true/false |
If true, the booking can be upgraded. |
Notes |
string |
- | Additional information about the booking. |
NumCars |
unsignedByte |
- | The number of cars rented. |
NumPersons |
unsignedByte |
- | The number of people including the driver that the rental is for. |
PhoneNumber |
string |
- | The phone number for the user. |
PickupDeliveryAddress1 |
string |
- | The AddressLine1 for the pick-up address when the rental service offers pick-up. |
PickupDeliveryAddressType |
string |
- | The type of address for the pick-up address when the rental service offers pick-up. |
PickupDeliveryCategory |
string |
- | The category for the pick-up address when the rental service offers pick-up. |
PickupDeliveryCityCode |
string |
- | The IATA airport code for the pick-up address when the rental service offers pick-up. |
PickupDeliveryCity |
string |
- | The city for the pick-up address when the rental service offers pick-up. |
PickupDeliveryCountry |
string |
- | The country for the pick-up address when the rental service offers pick-up. |
PickupDeliveryLatitude |
string |
- | The latitude for the pick-up address when the rental service offers pick-up. |
PickupDeliveryLongitude |
string |
- | The longitude for the pick-up address when the rental service offers pick-up. |
PickupDeliveryNumber |
string |
- | The number for the pick-up address when the rental service offers pick-up. |
PickupDeliveryPhoneNumber |
string |
- | The phone number for the pick-up address when the rental service offers pick-up. |
PickupDeliveryPostalCode |
string |
- | The postal code for the pick-up address when the rental service offers pick-up. |
PickupDeliveryState |
string |
- | The state for the pick-up address when the rental service offers pick-up. |
RateCode |
string |
- | The rate code for the booking. |
RateType |
string |
- | The rate type for the booking. |
Remarks |
type |
Remark Element |
Remarks on the segment. |
SpecialEquipment |
string |
- | Any special equipment required by the renter. |
SpecialInstructions |
string |
- | Additional instructions regarding the booking. Maximum length: 256 |
StartAddress2 |
string |
- | The starting address for the booking. |
StartAddress |
string |
- | The starting address of the booking. |
StartCityCode |
string |
- | The IATA airport code for the starting address for the booking. |
StartCity |
string |
- | The starting address for the booking. |
StartCloseTime |
string |
- | The closing time for the pick-up location. |
StartCountry |
string |
- | The starting address for the booking. |
StartDateLocal |
dateTime |
YYYY-MM-DDThh:mm:ss |
The booking starting time and date, in the booking location's local time. |
StartDateUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The booking starting time and date, in UTC. |
StartLatitude |
string |
- | The latitude for the starting location of the booking. |
StartLocation |
string |
- | The starting location of the booking. |
StartLongitude |
string |
- | The longitude for the starting location of the booking. |
StartOpenTime |
string |
- | The opening time for the pick-up location. |
StartPostalCode |
string |
- | The starting address for the booking. |
StartState |
string |
- | The starting address for the booking. |
Status |
string |
- | The booking status. |
TimeZone |
string |
Olson or Windows Time Zones |
The time zone of the booking. |
TimeZoneID |
integer |
- | The ID for the time zone of the booking. |
TotalRate |
decimal |
- | The total rate amount of the booking. |
Transmission |
string |
- | The character code that indicates if the car has auto-transmission. Supported values: A - Auto, M - Manual |
UpgradedDateTime |
dateTime |
YYYY-MM-DDThh:mm:ss |
The date and time the booking was upgraded. |
VendorName |
string |
- | The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary. |
VendorFlags |
string |
- | Not used |
Vendor |
string |
- | The two letter GDS vendor code. |
Dining Segment Element
| Name | Type | Format | Description |
|---|---|---|---|
CancellationNumber |
string |
- | The cancellation number from the vendor. This field should be set when you cancel a segment. |
Charges |
type |
Charge Detail Element |
List of charges for this booking. |
ConfirmationNumber |
string |
- | The confirmation number from the vendor. |
DateCancelledUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The date the booking was cancelled, in UTC. |
DateCreatedUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The date the booking was created, in UTC. |
DateModifiedUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The date the booking was modified, in UTC. |
EndDateLocal |
dateTime |
YYYY-MM-DDThh:mm:ss |
The booking ending time and date, in the booking location's local time. |
EndDateUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The booking ending time and date, in UTC. |
FrequentTravelerId |
string |
- | The loyalty program ID for the user. |
IsPreferredVendor |
integer |
- | If true, the restaurant is marked as a preferred property by the company. |
IsUpgradeAllowed |
boolean |
true/false |
If true, the booking can be upgraded. |
Name |
string |
- | The name of the restaurant. Maximum length: 80 |
Notes |
string |
- | Additional information about the booking. |
NumPersons |
unsignedByte |
- | The number of persons for the booking. |
PhoneNumber |
string |
- | The restaurant phone number. |
Remarks |
type |
Remark Element |
Remarks on the segment. |
ReservationID |
string |
- | The ID for restaurant reservation. |
StartAddress |
string |
- | The restaurant address. Maximum length: 80 |
StartAddress2 |
string |
- | The restaurant address. Maximum length: 80 |
StartCity |
string |
- | The restaurant address. Maximum length: 50 |
StartCountry |
string |
- | The restaurant address. |
StartDateLocal |
dateTime |
YYYY-MM-DDThh:mm:ss |
The booking starting time and date, in the booking location's local time. |
StartDateUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The booking starting time and date, in UTC. |
StartLatitude |
string |
- | The latitude of the restaurant. |
StartLongitude |
string |
- | The longitude of the restaurant. |
StartPostalCode |
string |
- | The restaurant address. Maximum length: 24 |
StartState |
string |
- | The restaurant address. Maximum length: 50 |
Status |
string |
- | The status of the segment. |
TimeZone |
string |
Olson or Windows Time Zones |
The time zone of the booking. |
TimeZoneID |
integer |
- | The ID for the time zone of the booking. |
UpgradedDateTime |
dateTime |
YYYY-MM-DDThh:mm:ss |
The date and time the booking was upgraded. |
Vendor |
string |
- | The two letter GDS vendor code. |
VendorFlags |
string |
- | Not used |
VendorName |
string |
- | The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary. |
Hotel Segment Element
| Name | Type | Format | Description |
|---|---|---|---|
Breakfast |
boolean |
true/false |
Indicates if breakfast is included with hotel stay. |
CancellationNumber |
string |
- | The cancellation number from the vendor. This field should be set when you cancel a segment. |
CancellationPolicy |
string |
- | The cancellation policy from the vendor. |
Charges |
type |
Charge Detail Element |
List of charges for this booking. |
CheckinTime |
string |
- | The check in time for the hotel booking. |
CheckoutTime |
string |
- | The check out time for the hotel booking. |
ConfirmationNumber |
string |
- | The confirmation number from the vendor. |
Currency |
string |
- | The 3-letter ISO 4217 currency code for the booking. |
DailyRate |
decimal |
- | Average per day rate for the hotel. If the rate varies over the duration, it can be specified using the charges model. |
DateCancelledUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The date the booking was cancelled, in UTC. |
DateCreatedUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The date the booking was created, in UTC. |
DateModifiedUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The date the booking was modified, in UTC. |
DirectBill |
boolean |
true/false |
Indicates the hotel will bill the company directly. |
DiscountCode |
string |
- | The discount code for the booking. |
Email |
string |
- | Email for the hotel. |
EndDateLocal |
dateTime |
YYYY-MM-DDThh:mm:ss |
The booking ending time and date, in the booking location's local time. |
EndDateUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The booking ending time and date, in UTC. |
EquipmentCode |
string |
- | Not used. |
FaxNumber |
string |
- | Fax number for the hotel. |
FrequentTravelerId |
string |
- | The traveler’s ID for the frequent traveler reward program. |
HotelPropertyID |
string |
- | The hotel's property ID. |
IncludedCustomAmenities |
string |
- | Not used. |
IsGhostCard |
boolean |
true/false |
Indicates if a payment was made using a shared corporate credit card. |
IsPreferredVendor |
integer |
- | If true, the hotel is marked as a preferred property by the company. |
IsUpgradeAllowed |
boolean |
true/false |
If true, the booking can be upgraded. |
ModificationCode |
string |
- | The code for the modification to the booking. |
Name |
string |
- | The hotel name for the booking. |
Notes |
string |
- | Additional information about the booking. |
NumPersons |
unsignedByte |
- | The number of people the booking is for. |
NumRooms |
unsignedByte |
- | The number of rooms the booking is for. |
Parking |
boolean |
true/false |
Indicates if the hotel reservation includes parking. |
PartnerMembershipId |
string |
- | The membership ID of the partner associated with the booking. |
PassiveType |
string |
- | The type of the booking. |
PhoneNumber |
string |
- | The phone number for the booking. |
RateAccess |
string |
- | The rate access for the booking. |
RateCode |
string |
- | The rate code for the booking. |
RateType |
string |
- | The rate type for the booking. |
RoomDescription |
string |
- | The room description for the booking. Maximum length: 200 |
RoomType |
string |
- | The room type for the booking. |
SpecialInstructions |
string |
- | Additional instructions regarding the booking. Maximum length: 256 |
StartAddress |
string |
- | The starting address of the booking. |
StartAddress2 |
string |
- | The starting address for the booking. |
StartCity |
string |
- | The starting address for the booking. |
StartCityCode |
string |
- | The IATA airport code for the starting address for the booking. |
StartCountry |
string |
- | The starting address for the booking. |
StartDateLocal |
dateTime |
YYYY-MM-DDThh:mm:ss |
The booking starting time and date, in the booking location's local time. |
StartDateUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The booking starting time and date, in UTC. |
StartLatitude |
string |
- | The latitude for the starting location of the booking. |
StartLongitude |
string |
- | The longitude for the starting location of the booking. |
StartPostalCode |
string |
- | The starting address for the booking. |
StartState |
string |
- | The starting address for the booking. |
Status |
string |
- | The booking status. |
TimeZone |
string |
Olson or Windows Time Zones |
The time zone of the booking. |
TimeZoneID |
integer |
- | The ID for the time zone of the booking. |
TotalRate |
string |
- | The total rate amount of the booking. |
UpgradedDateTime |
dateTime |
YYYY-MM-DDThh:mm:ss |
The date and time the booking was upgraded. |
Vendor |
string |
- | The two letter GDS vendor code. |
VendorFlags |
string |
- | Not used |
VendorName |
string |
- | The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary. |
WiFi |
boolean |
true/false |
Indicates if hotel reservation includes WIFI. |
Parking Segment Element
| Name | Type | Format | Description |
|---|---|---|---|
CancellationNumber |
string |
- | The cancellation number from the vendor. This field should be set when you cancel a segment. |
Charges |
type |
Charge Detail Element |
List of charges for this booking. |
ClassOfService |
string |
- | The class of the booking. |
ConfirmationNumber |
string |
- | The confirmation number from the vendor. |
Currency |
string |
- | The 3-letter ISO 4217 currency code for the booking. |
DateCancelledUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The date the booking was cancelled, in UTC. |
DateCreatedUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The date the booking was created, in UTC. |
DateModifiedUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The date the booking was modified, in UTC. |
EndDateLocal |
dateTime |
YYYY-MM-DDThh:mm:ss |
The booking ending time and date, in the booking location's local time. |
EndDateUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The booking ending time and date, in UTC. |
FrequentTravelerId |
string |
- | The traveler’s ID for the frequent traveler reward program. |
IsPreferredVendor |
integer |
If true, the parking company is marked as preferred by the company. |
|
IsUpgradeAllowed |
boolean |
true/false |
If true, the booking can be upgraded. |
Name |
string |
- | Name of the parking facility. |
Notes |
string |
- | Additional information about the booking. |
OperatedByVendor |
string |
- | The operating vendor of the booking. |
ParkingLocationId |
string |
- | The location of the parking booking. |
PhoneNumber |
string |
- | The parking phone number. |
Pin |
string |
- | The PIN number for the booking. |
RateCode |
string |
- | The vendor's code for the rate of the booking. |
Remarks |
type |
Remark Element |
Remarks on the segment. |
StartAddress |
string |
- | The starting address of the booking. |
StartAddress2 |
string |
- | The starting address of the booking. |
StartCity |
string |
- | The starting address of the booking. |
StartCityCode |
string |
- | The IATA airport code for the starting city of the booking. |
StartCountry |
string |
- | The starting address of the booking. |
StartDateLocal |
dateTime |
YYYY-MM-DDThh:mm:ss |
The starting date of travel for this segment, in the local time of to the starting point. |
StartDateUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The starting date of travel for this segment, in UTC. |
StartLocation |
string |
- | The parking location. |
StartPostalCode |
string |
- | The starting address of the booking. Maximum length: 24 |
StartState |
string |
- | The starting address of the booking. Maximum length: 50 |
Status |
string |
- | The booking status. |
TimeZone |
string |
Olson or Windows Time Zones |
The time zone of the booking. |
TimeZoneID |
integer |
- | The ID for the time zone of the booking. |
TotalRate |
string |
- | The total rate amount of the booking. |
UpgradedDateTime |
dateTime |
YYYY-MM-DDThh:mm:ss |
The date and time the booking was upgraded. |
Vendor |
string |
The two letter GDS vendor code. | |
VendorFlags |
string |
- | Not used |
VendorName |
string |
- | The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary. |
Rail Segment Element
| Name | Type | Format | Description |
|---|---|---|---|
Amenities |
string |
- | The booked amenities. |
Cabin |
string |
- | The cabin identifier. |
CancellationNumber |
string |
- | The cancellation number from the vendor. This field should be set when you cancel a segment. |
CarbonEmissionLbs |
decimal |
- | The pounds of carbon emission for this booking. |
CarbonModel |
integer |
- | The model used to calculate the carbon emissions. |
Charges |
type |
Charge Detail Element |
List of charges for this booking. |
ClassOfService |
string |
- | The class of the booking. |
ConfirmationNumber |
string |
- | The confirmation number from the vendor. |
Currency |
string |
- | The 3-letter ISO 4217 currency code for the booking. |
DateCancelledUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The date the booking was cancelled, in UTC. |
DateCreatedUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The date the booking was created, in UTC. |
DateModifiedUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The date the booking was modified, in UTC. |
DiscountCode |
string |
- | The discount code for the booking. |
Duration |
integer |
- | The duration of the trip booked. |
EndCity |
string |
- | The end city for the rail trip. |
EndCityCode |
string |
- | The IATA airport code for the end city of the trip. |
EndCountry |
string |
- | The country code for the booking. |
EndDateLocal |
dateTime |
YYYY-MM-DDThh:mm:ss |
The booking ending time and date, in the booking location's local time. |
EndDateUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The booking ending time and date, in UTC. |
EndLatitude |
string |
- | The latitude of the ending point of the booking. |
EndLongitude |
integer |
- | The longitude of the ending point of the booking. |
EndPlatform |
string |
- | The ending platform location of the booking. |
EndRailStation |
string |
- | The code for the ending station of the booking. |
EndRailStationName |
string |
- | The name of the ending station of the booking. |
EndState |
string |
- | The end state/province for the rail trip. |
Eticket |
integer |
- | The e-ticket number. |
FrequentTravelerId |
string |
- | The traveler’s ID for the frequent traveler reward program. |
IsPreferredVendor |
integer |
- | If true, the rail carrier is marked as a preferred rail carrier by the company. |
IsUpgradeAllowed |
boolean |
true/false |
If true, the booking can be upgraded. |
LegId |
string |
- | The trip leg ID. |
Meals |
string |
- | The booked meals. |
Miles |
integer |
- | The number of miles booked. |
Notes |
string |
- | Additional information about the booking. |
NumPersons |
unsignedByte |
- | The number of persons booked for the trip. |
NumStops |
unsignedByte |
- | The number of stops in the booking. |
OperatedByTrainNumber |
string |
- | The train identifier of the operating vendor of the booked trip. |
OperatedByVendor |
string |
- | The operating vendor of the booked trip. |
RateCode |
string |
- | The vendor's code for the rate of the booking. |
Remarks |
type |
Remark Element |
Remarks on the segment. |
RouteRestrictCode |
string |
- | The code to restrict the route of the booking. |
Seats |
array |
Rail Seat Element |
The booked seats. This parent element contains a Rail Seat element for each included seat. For more information, see the Rail Seat Elements table. |
SpecialInstructions |
string |
- | The instructions for the booking. Maximum length: 256 |
StartCity |
string |
- | The starting city of the booking. |
StartCityCode |
string |
- | The IATA airport code for the starting city of the booking. |
StartCountry |
string |
- | The starting country of the booking. |
StartDateLocal |
dateTime |
YYYY-MM-DDThh:mm:ss |
The starting date of travel for this segment, in the local time of to the starting point. |
StartDateUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The starting date of travel for this segment, in UTC. |
StartLatitude |
string |
- | The latitude of the starting location of the booking. |
StartLongitude |
string |
- | The longitude of the starting location of the booking. |
StartPlatform |
string |
- | The starting platform location of the booking. |
StartRailStation |
string |
- | The code of the starting station of the booking. |
StartRailStationName |
string |
- | The name of the starting station of the booking. |
StartState |
string |
- | The start state/province for the rail trip. |
Status |
string |
- | The booking status. |
TimeZone |
string |
Olson or Windows Time Zones |
The time zone of the booking. |
TimeZoneID |
integer |
- | The ID for the time zone of the booking. |
TotalRate |
decimal |
- | The total rate amount of the booking. |
TrainNumber |
string |
- | The number for the booked train. |
TrainTypeCode |
string |
- | The code for the type of train used in the booking. |
TrainTypeName |
string |
- | The name of the type of train used in the booking. |
TransportMode |
string |
- | The transport mode of the booking. |
UpgradedDateTime |
dateTime |
YYYY-MM-DDThh:mm:ss |
The date and time the booking was upgraded. |
Vendor |
string |
- | The two letter GDS vendor code. |
VendorFlags |
string |
- | Not used |
VendorName |
string |
- | The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary. |
WagonNumber |
string |
- | The wagon number of the train car. |
Ride Element
| Name | Type | Format | Description |
|---|---|---|---|
CancellationNumber |
string |
- | The cancellation number from the vendor. This field should be set when you cancel a segment. |
CancellationPolicy |
string |
- | The cancellation policy from the vendor. |
Charges |
type |
Charge Detail Element |
List of charges for this booking. |
ConfirmationNumber |
string |
- | The confirmation number from the vendor. |
Currency |
string |
- | The 3-letter ISO 4217 currency code for the booking. |
DateCancelledUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The date the booking was cancelled, in UTC. |
DateCreatedUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The date the booking was created, in UTC. |
DateModifiedUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The date the booking was modified, in UTC. |
DropoffInstructions |
string |
- | Instructions regarding the booking. |
Duration |
integer |
- | The duration of the booking. |
EndAddress |
string |
- | The ending address of the booking. |
EndAddress2 |
string |
- | The ending address of the booking. |
EndCity |
string |
- | The ending address of the booking. |
EndCityCode |
string |
- | The ending IATA airport code of the booking. |
EndCountry |
string |
- | The ending address of the booking. |
EndDateLocal |
dateTime |
YYYY-MM-DDThh:mm:ss |
The booking ending time and date, in the booking location's local time. |
EndDateUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The booking ending time and date, in UTC. |
EndLatitude |
string |
- | The latitude for the ending location of the booking. |
EndLocationCode |
string |
- | The ending location code of the booking. |
EndLongitude |
string |
- | The longitude of the ending point of the booking. |
EndPostalCode |
string |
- | The ending address of the booking. |
EndState |
string |
- | The ending address of the booking. |
IsGhostCard |
boolean |
true/false |
Indicates if a payment was made using a shared corporate credit card. |
IsPreferredVendor |
integer |
- | If true, the ride vendor is marked as a preferred ride vendor by the company. |
IsUpgradeAllowed |
boolean |
true/false |
If true, the booking can be upgraded. |
MeetingInstructions |
string |
- | The instructions for the meeting location of the booking. |
Miles |
integer |
- | The number of miles for the booking. |
Name |
string |
- | The name on the booking. |
Notes |
string |
- | Additional information about the booking. |
NumPersons |
unsignedByte |
- | The number of people included in the booking. |
NumberOfHours |
double |
- | The number of hours of the booking. |
OperatedByVendor |
string |
- | The operated by vendor for the booking. |
PassiveCityCode |
string |
- | The passive city code of the booking. |
PhoneNumber |
string |
- | The ride vendor phone number. |
PickupInstructions |
string |
- | Instructions regarding the booking. |
ProviderFeedback |
string |
- | Feedback from the provider. |
Rate |
string |
- | The rate for the booking. |
RateDescription |
string |
- | The rate description for the booking. |
RateNotes |
string |
- | The rate notes for the booking. |
RateType |
string |
- | The rate type for the booking. |
Remarks |
type |
Remark Element |
Remarks on the segment. |
ReservationID |
string |
- | The booking vendor’s reservation ID. |
SpecialInstructions |
string |
- | The special instructions for the ride. Maximum length: 256 |
StartAddress |
string |
- | The starting address of the booking. |
StartAddress2 |
string |
- | The starting address of the booking. |
StartCity |
string |
- | The starting address of the booking. |
StartCityCode |
string |
- | The starting IATA airport code of the booking. |
StartCountry |
string |
- | The starting address of the booking. |
StartDateLocal |
dateTime |
YYYY-MM-DDThh:mm:ss |
The booking starting time and date, in the booking location's local time. |
StartDateUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The booking starting time and date, in UTC. |
StartLatitude |
string |
The latitude of the booking start location. | |
StartLocation |
string |
- | The starting location of the booking. |
StartLocationCode |
string |
- | The code of the starting location of the booking. |
StartLocationName |
string |
- | The name of the starting location of the booking. |
StartLongitude |
string |
- | The longitude of the booking start location. |
StartPostalCode |
string |
- | The starting address of the booking. |
StartState |
string |
- | The starting address of the booking. |
TimeZone |
string |
Olson or Windows Time Zones |
The time zone of the booking. |
TimeZoneID |
integer |
- | The ID for the time zone of the booking. |
TotalRate |
decimal |
- | The total rate amount of the booking. |
UpgradedDateTime |
dateTime |
YYYY-MM-DDThh:mm:ss |
The date and time the booking was upgraded. |
Vendor |
string |
- | The two letter GDS vendor code. For an unknown vendor, use the code value: $$. |
VendorFlags |
string |
- | Not used |
VendorName |
string |
- | The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary. |
Travel Segment Element
| Name | Type | Format | Description |
|---|---|---|---|
CancellationNumber |
string | - | The cancellation number from the vendor. This field should be set when you cancel a segment. |
Charges |
type |
Charge Detail Element |
List of charges for this booking. |
ConfirmationNumber |
string |
- | The confirmation number from the vendor. |
Currency |
string |
- | The 3-letter ISO 4217 currency code for the booking. |
DailyRate |
decimal |
- | Average per day rate for the booking. If the rate varies over the duration, it can be specified using the charges model. |
DateCancelledUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The date the booking was cancelled, in UTC. |
DateCreatedUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The date the booking was created, in UTC. |
DateModifiedUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The date the booking was modified, in UTC. |
EndAddress |
string |
- | The ending address of the booking. |
EndAddress2 |
string |
- | The ending address of the booking. |
EndCity |
string |
- | The ending address of the booking. |
EndCityCode |
string |
- | The IATA airport code for the ending city of the booking. |
EndCountry |
string |
- | The ending address of the booking. |
EndDateLocal |
dateTime |
YYYY-MM-DDThh:mm:ss |
The booking ending time and date, in the booking location's local time. |
EndDateUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The booking ending time and date, in UTC. |
EndLatitude |
string |
- | The latitude for the ending location of the booking. |
EndLocation |
string |
- | The ending location of the booking. |
EndLongitude |
string |
- | The longitude of the ending point of the booking. |
EndPostalCode |
string |
- | The ending address of the booking. |
EndState |
string |
- | The ending address of the booking. |
IsGhostCard |
boolean |
true/false |
Indicates if a payment was made using a shared corporate credit card. |
Notes |
string |
- | Additional information about the booking. |
NumPersons |
unsignedByte |
- | The number of persons booked for the trip. |
PhoneNumber |
string |
- | The booking phone number. |
Remarks |
type |
Remark Element |
Remarks on the segment. |
SpecialInstructions |
string |
- | The instructions for the booking. Maximum length: 256 |
StartAddress |
string |
- | The starting address of the booking. |
StartAddress2 |
string |
- | The starting address of the booking. |
StartCity |
string |
- | The starting address of the booking. |
StartCityCode |
string |
- | The IATA airport code for the starting city of the booking. |
StartCountry |
string |
- | The starting address of the booking. |
StartDateLocal |
dateTime |
YYYY-MM-DDThh:mm:ss |
The starting date of travel for this segment, in the local time of to the starting point. |
StartDateUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The starting date of travel for this segment, in UTC. |
StartLatitude |
string |
- | The latitude of the booking. |
StartLocation |
string |
- | The start location of the booking. |
StartLongitude |
string |
- | The longitude of the booking. |
StartPostalCode |
string |
- | The starting address of the booking. Maximum length: 24 |
StartState |
string |
- | The starting address of the booking. Maximum length: 50 |
Status |
string |
- | The booking status. |
TimeZone |
string |
Olson or Windows Time Zones |
The time zone of the booking. |
TimeZoneID |
integer |
- | The ID for the time zone of the booking. |
TotalRate |
decimal |
- | The total rate amount of the booking. |
TransportMode |
string |
- | The transport mode of the booking. |
Vendor |
string |
- | The two letter GDS vendor code. |
VendorName |
string |
- | The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary. |
Accounting Line Element
| Name | Type | Format | Description |
|---|---|---|---|
AirlineCode |
string |
- | This is the 2-character IATA code assigned to the airline for which the ticket is issued |
AmountPaid |
string |
- | This should coincide with the amount charged to the form of payment, less any ticket credit application. This amount can also represent a fare difference ("add collect") on an exchanged ticket. Example: original ticket = $100.00, new ticket = $250.00, AmountPaid = $150.00 |
AmountPaidCurrency |
string |
- | The 3-letter ISO 4217 currency code of the amount paid. |
Ccnumber |
string |
- | Credit card number used for the accounting line |
Comment |
string |
- | Comments left for the accounting line. |
Commission |
string |
- | This is the amount of commission the agency (TMC) is taking on the ticket. Like most commissions, it should be accounted for in the total cost of the ticket. |
CommissionCurrency |
string |
- | The 3-letter ISO 4217 currency code of the commission. |
ExchangedTicketNumber |
string |
- | The original ticket number in the case where a ticket is being exchanged for another flight/fare. |
Fare |
string |
- | The cost for the flights booked on the ticket. |
FareCurrency |
string |
- | The 3-letter ISO 4217 currency code of the fare. |
Fopmethod |
string |
- | Form of payment method. |
IssueDate |
string |
- | The date the ticket was issued. |
McOType |
string |
- | MCO = Miscellaneous Charge Order. MCOs are used as "virtual ticket numbers" or tracking numbers for agency service fees, as well as residual ticket credits (example: original ticket = $100.00, new ticket = $50.00, Residual/Credit issued as MCO = $50.00) |
Tax |
string |
- | Total tax applied to the airfare. |
TaxCurrency |
string |
- | The 3-letter ISO 4217 currency code for the taxes. |
TranControlNbr |
string |
- | "Transaction Control Number" This is the 10-digit number that follows the plating number on a ticket. |
TranPlatingNbr |
string |
- | "Transaction Plating Number." All IATA-authorized airlines are issued a 3-digit number that designates the airline on the ticket. Examples: 006 = Delta, 001 = American Airlines, 016 = United Airlines. |
Air Seat Element
| Name | Type | Format | Description |
|---|---|---|---|
PassengerRph |
integer |
- | The passenger assigned to the seat. |
SeatNumber |
string |
- | The number of the seat. |
Status |
string |
- | The status for the seat. |
Airline Ticket Coupon Element
| Name | Type | Format | Description |
|---|---|---|---|
ClassOfService |
string |
- | Class of service for the coupon. |
CouponNumber |
integer |
- | ID for the coupon. |
CouponStatus |
string |
- | Status of the coupon. |
EndCityCode |
string |
- | End city code for the coupon. |
FlightNumber |
string |
- | Flight number for the coupon. |
NotValidAfterDate |
dateTime |
YYYY-MM-DDThh:mm:ss |
Timestamp for when the coupon is not valid after. |
NotValidBeforeDate |
dateTime |
YYYY-MM-DDThh:mm:ss |
Timestamp for when the coupon is not valid before. |
RateCode |
string |
- | The rate code for the coupon. |
StartCityCode |
string |
- | Start city code for the coupon. |
StartDateLocal |
dateTime |
YYYY-MM-DDThh:mm:ss |
Local timestamp for when the flight departs. |
Status |
string |
- | Status of the coupon. |
TicketDesignator |
string |
- | A code on airline tickets to indicate what type of discount is applied, such as for a child or infant, or airline employee. |
Vendor |
string |
- | 2 letter vendor code for the coupon. |
Airline Ticket Exchanges Element
| Name | Type | Format | Description |
|---|---|---|---|
Amount |
decimal |
- | Amount exchanged. |
AppliedSegment1 |
integer |
- | Internal use. |
AppliedSegment10 |
integer |
- | Internal use. |
AppliedSegment2 |
unsignedByte |
- | Internal use. |
AppliedSegment3 |
integer |
- | Internal use. |
AppliedSegment4 |
integer |
- | Internal use. |
AppliedSegment5 |
integer |
- | Internal use. |
AppliedSegment6 |
integer |
- | Internal use. |
AppliedSegment7 |
integer |
- | Internal use. |
AppliedSegment8 |
integer |
- | Internal use. |
AppliedSegment9 |
integer |
- | Internal use. |
Currency |
string |
- | The 3-letter ISO 4217 currency code for the ticket. |
DateModifiedUtc |
dateTime |
YYYY-MM-DDThh:mm:ss |
The UTC timestamp of ticket exchange modification. |
OldRecordLocator |
string |
- | The unique identifier for a booking. This is often six alphanumeric characters, but can have other formats depending on the booking source. |
PlatingCarrierNumericCode |
string |
- | The three-digit ticket number that indicates the airline code. Examples: 001 - American, 005 - Continental, 006 - Delta, 012 - Northwest |
PlatingControlNumber |
string |
- | Ten digits of the ticket number that indicates the ticket control number. |
Airline Ticket Fare Breakups Element
| Name | Type | Format | Description |
|---|---|---|---|
BaseFare |
decimal |
- | Fare without any tax penalities. |
ClassOfService |
string |
- | Class of fare for the ticket. |
Currency |
string |
- | The 3-letter ISO 4217 currency code |
EndCityCode |
string |
- | End city code for the ticket. |
IsRefundable |
boolean |
true/false |
Indicates if the ticket is refundable. |
StartCityCode |
string |
- | Start city code for the ticket. |
TotalFare |
decimal |
- | Total cost of the ticket. |
Vendor |
string |
- | 2 letter vendor code for the ticket fare. |
Custom Attribute Element
| Name | Type | Format | Description |
|---|---|---|---|
Data |
string |
- | The value set for the custom attribute. |
DataType |
string |
- | The type of the custom attribute like numeric, string, etc. |
DisplayOnItinerary |
boolean |
true/false |
The condition that determines whether the attribute is displayed on the itinerary. |
DisplayTitle |
string |
- | ignore this - this is the title of the custom attribute to display on the Concur-UI. |
ExternalId |
integer |
- | THe internal reference to the definition of the custom attribute definition. |
Name |
string |
- | Work the Concur Travel Administrator for the company to get a list of configured custom trip attributes (known as Custom Trip Fields in the Concur documentation, not to be confused with Custom Profile fields). This is the name of the custom attribute configured by the admin. |
Frequent Traveler Program Element
| Name | Type | Format | Description |
|---|---|---|---|
FrequentFlyer |
array |
Frequent Flyer Element |
Frequent flyer information |
RailProgram |
array |
Rail Program Element |
Advantage program information |
Frequent Flyer Element
| Name | Type | Format | Description |
|---|---|---|---|
AirlineVendor |
string |
- | The 2 letter vendor code of the frequent flyer program. |
Description |
string |
- | The program descirption. |
DiscountProgramExpirationDate |
dateTime |
YYYY-MM-DDThh:mm:ss |
The date the discount program enrollment expires. |
DiscountProgramType |
string |
- | The type of the discount program. |
FrequentFlyerNumber |
string |
- | The passenger's identifier for the program. |
Status |
string |
- | The passenger's program status. |
StatusExpirationDate |
dateTime |
YYYY-MM-DDThh:mm:ss |
The expiration date for the passenger's program status. |
Rail Program Element
| Name | Type | Format | Description |
|---|---|---|---|
Description |
string |
- | The description of the discount program. |
DiscountProgramExpirationDate |
dateTime |
YYYY-MM-DDThh:mm:ss |
The date the discount program enrollment expires. |
DiscountProgramType |
string |
- | The type of the discount program. |
ProgramNumber |
string |
- | The passenger's identifier for the program. |
Status |
string |
- | The passenger's program status. |
StatusExpirationDate |
dateTime |
YYYY-MM-DDThh:mm:ss |
The expiration date for the passenger's program status. |
Rail Seat Element
| Name | Type | Format | Description |
|---|---|---|---|
Amenities |
string |
- | The amenities for the seat. |
BerthPosition |
string |
- | The berth location of the seat. |
Deck |
string |
- | Which deck the seat is on. |
FacingForward |
string |
- | Whether the seat is facing forward. |
FareSpaceComfort |
string |
- | The space around the seat. |
PassengerRph |
integer |
- | Which passenger the seat is assigned to. |
SeatNumber |
string |
- | The number of the seat. |
SeatPosition |
string |
- | The location of the seat. |
SeatType |
string |
- | The type of the seat. |
SpaceType |
string |
- | The type of space around the seat. |
Status |
string |
- | The status of the seat booking. |
WagonNumber |
string |
- | The number of the wagon the seat is on. |
WagonType |
string |
- | The type of wagon the seat is on. |
Rule Violation Element
| Name | Type | Format | Description |
|---|---|---|---|
CompanyReasonCode |
string |
- | Internal Only. The reason code congifured by the Travel Admin to identify the violation of policy for the booked trip |
CompanyRuleText |
string |
- | Internal Only. The rule text configured by the Travel Admin. |
ViolationReasonCode |
integer |
- | Internal Only. The integer identifier for the reason code selected when the user violates the rules/policy configured by the Travel Admin. |
Segment Option Item Element
| Name | Type | Format | Description |
|---|---|---|---|
Flight |
array |
Segment Option Flight Type Element |
The flight options. |
SegmentIndex |
string |
- | The index of the segment among the options. |
StatusCode |
string |
- | The status of the segment option. |
TimeStamp |
string |
- | The timestamp for the segment option. |
Segment Option Flight Type Element
| Name | Type | Format | Description |
|---|---|---|---|
ArrAirp |
string |
- | Arrival airport. |
Cabin |
string |
- | Cabin for the flight. |
Carrier |
string |
- | The flight carrier. |
DepAirp |
string |
- | Departure airport. |
FlightNum |
string |
- | The flight number. |
Tax Element
| Name | Type | Format | Description |
|---|---|---|---|
TaxAmount |
decimal |
- | The amount of the tax. |
TaxAuthority |
string |
- | The entity levying the tax |
TaxName |
string |
- | The name of the tax. |
TaxRate |
decimal |
- | The tax percentage rate. |
TaxType |
string |
- | The type of the tax. |
Error Schema
Errors Element
| Name | Type | Format | Description |
|---|---|---|---|
errors |
array |
Error Element |
- |
Error Element
| Name | Type | Format | Description |
|---|---|---|---|
errorCode |
string |
- | Code for the error. |
errorMessage |
string |
- | Message for the error. |
errors |
array |
Error Element |
List of sub errors. |
Booking
The Booking resource represents booking segments in the SAP Concur Travel system. TripLink suppliers use this resource to display a subset of the full booking fields.
Version
Version 1.1
URI
/travel/booking/v1.1/{query_parameters}
Scope
In order to obtain itinerary data when making Itinerary API calls, the value of the OAuth scope parameter must be set to: ITINER
Create or Update Booking
Creates a new booking or updates an existing booking. A new booking will be assigned to the specified trip, or if no trip is specified, the first itinerary that spans the booking dates. If no trip is specified and no itinerary exists that spans the booking dates, a new itinerary will be created.
This endpoint can be used to create/update bookings for a user that is not the OAuth consumer. This is most often done when a travel supplier or Travel Management Company needs to create/update a booking on behalf of a user. The supplier or TMC must be registered with SAP Concur, and must have an account that has one of the following user roles: Web Services Administrator for Professional, or Can Administer for Standard.
Request
POST /api/travel/booking/v1.0?tripId=12345678 HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Request Parameters
Query Parameters - Optional
- tripId={tripId} The unique identifier for the trip. Supplied in order to add a booking to an existing trip.
- userid_type=login_id&userid_value={loginID} The SAP Concur login ID of the user who owns the booking. Only provided when the booking owner is not the OAuth consumer. Can only be used when the OAuth consumer has the required user role.
Examples:
https://www.concursolutions.com/api/travel/booking/v1.1?tripId={tripId}
https://www.concursolutions.com/api/travel/booking/v1.1?userid_type=login_id&userid_value={loginID}
Content Type
application/xml
Authorization Header
Authorization header with OAuth token for a valid SAP Concur user. In order to create or update booking for anyone other than the OAuth consumer, the OAuth consumer must have one of the following user roles in SAP Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard.
Create or Update Booking Request Schema
The request contains a Booking parent element with the following child elements:
| Required Element | Description |
|---|---|
BookingSource |
The supplier's name. |
RecordLocator |
Record locator for this booking. This is often six alphanumeric characters but can have other formats depending on the booking source |
| Optional Element | Description |
|---|---|
DateBookedLocal |
The date the booking was created, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss |
FormOfPaymentName |
The name of the form of payment for the booking. |
FormOfPaymentType |
The type of the form of payment. |
TicketMailingAddress |
The mailing address for the booked ticket, if available. |
TicketPickupLocation |
The pickup location for the booked ticket, if available. |
TicketPickupNumber |
The confirmation number to pick up the booked ticket, if available. |
AirfareQuotes |
List of stored airfare quotes for this booking. |
AirlineTickets |
List of Airline Tickets for this booking. |
Charges |
List of Charges for this booking. |
MiscChargeOrders |
List of Miscellaneous AirCharges for this booking. |
Passengers |
The Passengers element contains a Passenger child element for each booked passenger. The description of each child element can be seen in a subsequent table. |
PassPrograms |
List of Pass Programs for this booking. |
PhoneNumbers |
List of Phone numbers associated with this booking. |
RailPayments |
List of Rail payments associated with rail segments in this booking. |
Segments |
List of Segments in this booking. This parent element contains one or more Air, Car, Hotel, Dining, Ride, Rail, Parking, or Event parent elements for the booking. Refer to Booking Object Elements for more information about the child elements contained in the booking elements. |
Delivery |
The method this booking was delivered. |
WaitListSegments |
The segments that the traveler is waitlisted for this booking. |
Warnings |
The warnings associated with the booking. |
WebAddresses |
List of web addresses such as emails, pickup URLs, etc. associated with this bookings |
Passenger Child Elements
| Required Element | Description |
|---|---|
NameFirst |
The first name of the passenger. |
NameLast |
The last name of the passenger. |
| Optional Element | Description |
|---|---|
NameMiddle |
The middle name of the passenger. |
NamePrefix |
The name prefix of the passenger. |
NameRemark |
Additional details about the passenger's name. |
NameSuffix |
The name suffix of the passenger. |
NameTitle |
The title of the passenger. |
TextName |
The user's full name as entered in the booking tool if different from the name in the database. |
FrequentTravelerProgram |
Passenger's loyalty programs |
Response
This function returns the full trip details, as documented in the Response of the Get Itinerary Details function.
If the end user updates an existing reservation which results in a new confirmation number, the old booking must be explicitly cancelled in addition to posting the new booking to SAP Concur. If the previous booking is not cancelled, the user will see both bookings in their SAP Concur trip list.
Examples
Example 1: XML Example Request
POST /api/travel/booking/v1.0?tripId=12345678 HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
...
<Booking xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Segments>
<Car>
<Vendor>AL</Vendor>
<VendorName>Alamo</VendorName>
<Status>HK</Status>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<EndDateLocal>2013-12-23T12:00:00</EndDateLocal>
<StartDateUtc>2013-12-21T20:00:00</StartDateUtc>
<EndDateUtc>2013-12-23T20:00:00</EndDateUtc>
<ConfirmationNumber>F16726AIUS</ConfirmationNumber>
<DateCreatedUtc>2012-07-22T11:55:42</DateCreatedUtc>
<DateModifiedUtc>2012-07-22T11:55:42</DateModifiedUtc>
<StartCityCode>SEA</StartCityCode>
<EndCityCode>SEA</EndCityCode>
<StartLocation>SEA</StartLocation>
<EndLocation>SEA</EndLocation>
<Class>E</Class>
<Body>C</Body>
<Transmission>A</Transmission>
<AirCondition>R</AirCondition>
<NumPersons>1</NumPersons>
<NumCars>1</NumCars>
<DiscountCode>4321</DiscountCode>
<DailyRate>35.0000</DailyRate>
<TotalRate>105.0000</TotalRate>
<RateType>D</RateType>
<Currency>USD</Currency>
</Car>
</Segments>
<RecordLocator>PANAMA50</RecordLocator>
<BookingSource>Alamo</BookingSource>
<DateCreatedUtc>2012-07-22T11:55:42</DateCreatedUtc>
<DateModifiedUtc>2012-07-22T11:55:42</DateModifiedUtc>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<Passengers>
<Passenger>
<PassengerKey>0</PassengerKey>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
</Booking>
Example 2: XML Example of Successful Response
<Itinerary xmlns="https://www.concursolutions.com/api/travel/trip/2010/06">
<id>https://www.concursolutions.com/api/travel/trip/v1.1/CNQR1234567890</id>
<ItinLocator>CNQR1234567890</ItinLocator>
<ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
<ItinSourceName>TravelSupplier</ItinSourceName>
<TripName>Trip to Seattle</TripName>
<Comments />
<StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
<EndDateLocal>2013-12-23T23:59:00</EndDateLocal>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<BookedVia>EveryGDS</BookedVia>
<BookedByFirstName>Chris</BookedByFirstName>
<BookedByLastName>Miller</BookedByLastName>
<DateBookedLocal>2012-07-24T19:15:52</DateBookedLocal>
<Booking>
<Segments>
<Car>
<Vendor>AL</Vendor>
<VendorName>Alamo</VendorName>
<Status>HK</Status>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<EndDateLocal>2013-12-23T12:00:00</EndDateLocal>
<StartDateUtc>2013-12-21T20:00:00</StartDateUtc>
<EndDateUtc>2013-12-23T20:00:00</EndDateUtc>
<ConfirmationNumber>F16726AIUS</ConfirmationNumber>
<DateCreatedUtc>2012-07-22T11:55:42</DateCreatedUtc>
<DateModifiedUtc>2012-07-22T11:55:42</DateModifiedUtc>
<StartCityCode>SEA</StartCityCode>
<EndCityCode>SEA</EndCityCode>
<StartLocation>SEA</StartLocation>
<EndLocation>SEA</EndLocation>
<Class>E</Class>
<Body>C</Body>
<Transmission>A</Transmission>
<AirCondition>R</AirCondition>
<NumPersons>1</NumPersons>
<NumCars>1</NumCars>
<DiscountCode>4321</DiscountCode>
<DailyRate>35.0000</DailyRate>
<TotalRate>105.0000</TotalRate>
<RateType>D</RateType>
<Currency>USD</Currency>
</Car>
</Segments>
<RecordLocator>PANAMA50</RecordLocator>
<BookingSource>Alamo</BookingSource>
<DateCreatedUtc>2012-07-22T11:55:42</DateCreatedUtc>
<DateModifiedUtc>2012-07-22T11:55:42</DateModifiedUtc>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<ItinSourceName>TravelSupplier</ItinSourceName>
<Passengers>
<Passenger>
<PassengerKey>0</PassengerKey>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
</Booking>
</Itinerary>
Cancel a Booking
Cancels an existing booking. By default, the OAuth consumer should be the owner of the booking. This endpoint can also be used to cancel bookings that the OAuth consumer does not own. This is most often done when a Travel Management Company needs to cancel bookings on behalf of a user. The TMC must be registered with SAP Concur and have a SAP Concur account that has one of the following user roles: Web Services Administrator for Professional, or Can Administer for Standard.
NOTE:
- Booking records can only be updated by the booking source that created them. SAP Concur verifies the source information before processing the request.
Example:
https://{baseUri}/api/travel/booking/v1.1/cancel?bookingSource={Supplier}&confirmationNumber={confnum}
Request
POST /api/travel/booking/v1.1/cancel?bookingSource={FastTravel}&confirmationNumber={098765431} HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Request Parameters
Query Parameters - Required
- cancel?bookingSource={Supplier}
The cancel keyword and the unique identifier for the supplier, configured by SAP Concur during the application review. The bookingSource must match the Supplier Name associated with the booking.
- confirmationNumber={confnum}
The confirmation number for the booking to cancel.
Example:
https://www.concursolutions.com/api/travel/booking/v1.1/cancel?bookingSource={Supplier}&confirmationNumber={confnum}
Query Parameters - Optional
- userid_type=login_id&userid_value={loginID}
The SAP Concur login ID of the user who owns the booking. Only provided when the booking owner is not the OAuth consumer. Can only be used when the OAuth consumer has the required user role.
Example:
https://www.concursolutions.com/api/travel/booking/v1.1/cancel?bookingSource={Supplier}&confirmationNumber={confnum}&userid_type=login_id&userid_value={loginID}
Content Type
application/xml
Authorization Header
The authorization header must have an OAuth token for valid SAP Concur user. The OAuth consumer must be registered as a Supplier or TMC with SAP Concur, and must have one of the following user roles in SAP Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard.
Response
This function returns the full booking details, as specified in the Booking Object Elements section.
If the booking is not found, the function returns a HTTP 404 error and the following element:
Status: This element contains the value: NotFound.
Examples
Examples 1: XML Example Request
POST /api/travel/booking/v1.1/cancel?bookingSource={FastTravel}&confirmationNumber={098765431} HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Examples 2: XML Example of Successful Response
<Car>
<Vendor>ZE</Vendor>
<Status>HK</Status>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
<TimeZoneId xsi:nil="true"/>
<StartDateUtc>2013-12-21T20:00:00</StartDateUtc>
<EndDateUtc>2013-12-24T20:00:00</EndDateUtc>
<ConfirmationNumber>0987654321</ConfirmationNumber>
<CancellationNumber>1029384756</CancellationNumber>
<DateCreatedUtc>2012-07-22T11:55:42</DateCreatedUtc>
<DateCancelledUtc>2012-07-25T14:21:35</DateCancelledUtc>
<DateModifiedUtc>2012-07-22T11:55:42</DateModifiedUtc>
<UpgradedDateTime xsi:nil="true"/>
<IsUpgradeAllowed xsi:nil="true"/>
<FrequentTravelerId/>
<StartCityCode>SEA</StartCityCode>
<EndCityCode>SEA</EndCityCode>
<StartLocation>SEA</StartLocation>
<EndLocation>SEA</EndLocation>
<Class>E</Class>
<Body>C</Body>
<Transmission>M</Transmission>
<AirCondition>R</AirCondition>
<PhoneNumber/>
<NumPersons xsi:nil="true"/>
<NumCars>1</NumCars>
<DiscountCode>346660</DiscountCode>
<Charges>
<Fixed>
<Description>Dropoff Fee</Description>
<Currency>USD</Currency>
<Amount>0.0000</Amount>
<StartDateLocal xsi:nil="true"/>
<IsPaid xsi:nil="true"/>
<SemanticsCode>DROPOFFFEE</SemanticsCode>
<SemanticsVendorType>C</SemanticsVendorType>
</Fixed>
<RateWithAllowance>
<Currency>USD</Currency>
<Amount>44.0000</Amount>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<IsPaid xsi:nil="true"/>
<SemanticsCode>DAYS</SemanticsCode>
<SemanticsVendorType>C</SemanticsVendorType>
<PerUnit>DAY</PerUnit>
<NumUnits>1.0000</NumUnits>
<AllowanceUnit/>
<AllowanceNumUnits>250.0000</AllowanceNumUnits>
<AllowanceAmount>0.2400</AllowanceAmount>
<AllowanceIsUnlimited>false</AllowanceIsUnlimited>
</RateWithAllowance>
</Charges>
<Remarks/>
<PerDiemLocation/>
</Car>
See Also
Trips
The Trips resource represents itineraries in the Concur Travel system. TripLink suppliers use this resource to display a subset of the full booking fields.
Version
1.1
URI
/travel/trip/v1.1/{query_parameters}
Scope
In order to obtain itinerary data when making Itinerary API calls, the value of the OAuth scope parameter must be set to: ITINER
Operations
Get Trip Summaries
The Get Itinerary Summaries endpoint is used for retrieving trip summaries for the traveler whose account is associated with the OAuth access token used to make the API call. This endpoint can also be used to get trip summaries for a different user or the whole company. This is usually done when a Travel Management Company (TMC) needs to get trip summaries on behalf of a user or company.
Best Practices
- When extracting past data:
- Extract a month of trip summaries to gauge volume. If hundreds are returned, then adjust extraction to weekly.
- Do not extract more than a year of data at any given time regardless of the volume. For longer look backs, extract 6 month segments maximum at a time.
- Do not multi-thread requests to retrieve multiple pages of data. Concurrent requests will impact your application’s performance.
- Itineraries change frequently. Changes do not necessarily indicate that the traveler modified their trip. If your application works with upcoming or in progress trips, be aware that you must evaluate the individual segments to determine whether it is a material change for your application.
- This API will only return itineraries that have been sent to Concur Travel; this includes travel booked within Concur Travel, TripIt, on TripLink supplier sites, and most bookings from your travel agency. Some customers may have multiple booking options which may mean not all employee trips are available via this API. A good rule of thumb: if the traveler sees the itinerary in their “trips” list, then you can retrieve it from this API.
Request
GET /travel/trip/v1.1/{query_parameters}
Query Parameters
All query parameters are optional.
To identify a specific user by login ID or XMLSyncID, you can specify the following request parameters:
| Parameter Name | Parameter Type | Data Type | Description |
|---|---|---|---|
startDate |
date |
dateTime |
The URL-encoded start date (in Coordinated Universal Time, or UTC) for the trip. Format: YYYY-MM-DD. If no query parameters are provided, the start date is set to today's date - 30 days. The request will only return trips that are ongoing during the provided dates, either starting on the date, or starting before the date and ongoing during the provided date. |
endDate |
date |
dateTime |
The URL-encoded UTC end date for the trip. Format: YYYY-MM-DD. If no query parameters are provided, the end date is set to today's date + 12 months. The request will only return trips that are ongoing during the provided dates, either ending on the date, or starting before the date and ongoing during the provided date. |
createdAfterDate |
date |
dateTime |
The URL-encoded UTC date for when the trip was created. The query string will return trips created on or after this date. Used with the createdBeforeDate for finding trips created during a date range. Format: YYYY-MM-DD. |
createdBeforeDate |
date |
dateTime |
The URL-encoded UTC date for when the trip was created. The query string will return trips created on or before this date. Used with the createdAfterDate for finding trips created during a date range. Format: YYYY-MM-DD. |
lastModifiedDate |
date |
dateTime |
The last modified UTC date of the trips and their associated bookings. This query string will return only the trips where the trip or any of its associated bookings have a last modified date that is greater or equal to the supplied time. The provided date/time can be anytime between now and the first date of trip creation in the database. The format is either the date or the date and time combined. |
bookingType |
type |
string |
The trip includes at least one booking of this type. Format: Air, Car, Dining, Hotel, Parking, Rail, or Ride. |
userid_type=login |
userid |
string |
The loginID is the user's SAP Concur login ID. This parameter can only be used if the OAuth consumer has one of the user roles listed above. |
userid_value |
userid |
string |
The userid_value of ALL can be sent to get trip summaries for all users at the company. This parameter can only be used if the OAuth consumer has one of the user roles listed above. |
includeMetadata |
true/false |
string |
The includeMetadata query parameter combined with the ItemsPerPage and Page query parameters cause the response to be divided into pages. The response is wrapped in a ConcurResponse parent element, with both the response details and the paging metadata included. If the ItemsPerPage query parameter is not sent, the response will default to 200 if the Page query parameter is sent, or 1000 if the Page query parameter is not set. If the Page query parameter is not sent, the response will default to page 1. |
ItemsPerPage |
number |
integer |
The includeMetadata query parameter combined with the ItemsPerPage and Page query parameters will cause the response to be divided into pages. The response will be wrapped in a ConcurResponse parent element, with both the response details and the paging metadata included. If the ItemsPerPage query parameter is not sent, the response will default to 200 if the Page query parameter is sent, or 1000 if the Page query parameter is not set. If the Page query parameter is not sent, the response will default to page 1. |
includeVirtualTrip |
flag |
integer |
Virtual trips are segments booked offline through the Concur Request product. Set the includeVirtualTrip query parameter to 1 to include those trips in the list. |
includeCanceledTrips |
true/false |
string |
The includeCanceledTrips query parameter will cause the request to also return trips with a status of Canceled. When this query parameter is set to true, the response will include the TripStatus element. |
includeGuestBookings |
true/false |
string |
The includeGuestBookings query parameter will cause the request to show guest bookings if set to true. It is set to false by default. |
Here are some examples of how to format GET requests using a combination of these query parameters:
- To get trip summaries for the entire company:
https://www.concursolutions.com/api/travel/trip/v1.1/?startDate={_startdate_}&endDate={_enddate_}_&_createdAfterDate={_date_}&createdBeforeDate={_date_}&lastModifiedDate={_date_}&bookingType={_type_}&userid_type=login&userid_value=ALL
The access token used to make the API call must be associated with an account that has the Admin user role.
- To get trip summaries for the account associated with the app making the call:
https://www.concursolutions.com/api/travel/trip/v1.1/?startDate={_startdate_}&endDate={_enddate_}_&_createdAfterDate={_date_}&createdBeforeDate={_date_}&lastModifiedDate={_date_}&bookingType={_type_}
The access token used to make the API call is associated with the account for the app making the call.
- To get trip summaries for a user with the specified login credentials:
https://www.concursolutions.com/api/travel/trip/v1.1/?startDate={_startdate_}&endDate={_enddate_}_&_createdAfterDate={_date_}&createdBeforeDate={_date_}&lastModifiedDate={_date_}&bookingType={_type_}&userid_type=login_id&userid_value={_loginID_}
The access token used to make the API call is associated with the SAP Concur account with the specified login credentials.
Headers
Authorization Header (Required)
Authorization: OAuth {access_token}
Where access_token is the OAuth 2.0 access token of the user whose itinerary information you want to retrieve. If you want to access company-wide itinerary information, the SAP Concur user account associated with the OAuth 2.0 access token must have one of these roles: Web Services Administrator for Professional or Can Administer for Standard.
Accept Header (optional)
application/xml
Get Trip Summaries Response Schema
The response returns an ItineraryInfoList parent element with an ItineraryInfo child element for each trip summary for the specified traveler. If the includeMetadata and ItemsPerPage query parameters are included in the request, the response will include a ConnectResponse parent element which contains a MetaData element with paging information and a Data element with an ItineraryInfoList child element. The response for this operation can be divided into pages for easier processing.
Data Elements
| Element Name | Data Type | Description |
|---|---|---|
ItineraryInfoList |
element |
Parent element with an ItineraryInfo child element for each trip summary for the specified traveler. |
ItineraryInfoList Elements
| Element Name | Data Type | Description |
|---|---|---|
ItineraryInfo |
element |
Parent element with the information about an itinerary for the specified user. |
ItineraryInfo Elements
| Element Name | Data Type | Description |
|---|---|---|
TripId |
string |
Encrypted trip identifier value. |
TripName |
string |
Name of the trip. |
TripStatus |
string |
The status of the trip. This element only appears if the includeCanceledTrips query parameter is used in the request. |
StartDateLocal |
dateTime |
The start date of the trip in the starting location’s timezone. Format: YYYY-MM-DDThh:mm:ss. |
EndDateLocal |
dateTime |
The end date of the trip in the ending location’s timezone. Format: YYYY-MM-DDThh:mm:ss. |
DateModifiedUtc |
dateTime |
The UTC date that this trip was last modified. Format: YYYY-MM-DDThh:mm:ss. |
UserLoginId |
string |
The user's login to SAP Concur. This element appears in the response of the GET /api/travel/trip/v1.1 operation when the OAuth 2.0 is access token is associated with an SAP Concur account with one of these roles: Web Services Administrator for Professional or Can Administer for Standard. |
id |
string |
Trip ID URI with encrypted ID. |
Metadata Element
The parent element of the paging information.
Paging Elements
| Element Name | Data Type | Description |
|---|---|---|
TotalPages |
integer |
The total number of pages the query returned. |
TotalItems |
integer |
The total number of itineraries the query returned. |
CurrentPage |
integer |
The page number for the set of results in the current response. |
ItemsPerPage |
integer |
The number of items set to display per page. |
PreviousPageURL |
string |
The URI to the previous page of results. This element will be empty when there are no previous pages. |
NextPageURL |
string |
The URI to the next set of results. This element will be empty when there are no next pages. |
Examples
Example 1: Get Trip Summaries by Start and End Date
Request
GET /api/travel/trip/v1.1/?startDate=2012%2F02%2F01&endDate=2013%2F12%2F31 HTTP/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
...
Response
HTTP/1.1 200 OK
Content-Type: application/xml
...
<?xml version="1.0" encoding="utf-8"?>
<ItineraryInfoList xmlns="http://www.concursolutions.com/api/travel/trip/2010/06" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<ItineraryInfo>
<TripId>naIzQJ0y2DBWjCIQOb2SHTsozwBsHDkdP</TripId>
<TripName>Trip from Baltimore to New York</TripName>
<StartDateLocal>2012-02-15T09:00:00</StartDateLocal>
<EndDateLocal>2012-02-21T17:30:00</EndDateLocal>
<UserLoginId>cm@example.com</UserLoginId>
<DateModifiedUtc>2012-02-14T17:13:07</DateModifiedUtc>
<id>https://www.concursolutions.com/api/travel/trip/v1.1/naIzQJ0y2DBWjCIQOb2SHTsozwBsHDkdP</id>
</ItineraryInfo>
<ItineraryInfo>
<TripId>I2uwiJJw8r7Owl3IWlSie9WIelxhAhwiL</TripId>
<TripName>Trip from Baltimore to Seattle</TripName>
<StartDateLocal>2012-03-26T09:00:00</StartDateLocal>
<EndDateLocal>2012-03-29T17:30:00</EndDateLocal>
<DateModifiedUtc>2012-03-24T19:00:00</DateModifiedUtc>
<UserLoginId>cm@example.com</UserLoginId>
<id>https://www.concursolutions.com/api/travel/trip/v1.1/I2uwiJJw8r7Owl3IWlSie9WIelxhAhwiL</id>
</ItineraryInfo>
</ItineraryInfoList>
Example 2: Get Trip Summary by Booking Type and Start Date Request
This request returns trip summaries for trips that started by the specified date for the specified booking type.
Request
GET /api/travel/trip/v1.1/?startDate=2015%2F01%2F01&bookingType=Air HTTP/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
...
Response
HTTP/1.1 200 OK
Content-Type: application/xml
...
<?xml version="1.0" encoding="utf-8"?>
<ItineraryInfoList xmlns="http://www.concursolutions.com/api/travel/trip/2010/06" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<ItineraryInfo>
<TripId>I2uwiJJw8r7OwCIQOb2SHTsozwBsSie9W</TripId>
<TripName>Trip by air from Seattle to San Francisco</TripName>
<StartDateLocal>2015-01-01T12:30:00</StartDateLocal>
<EndDateLocal>2015-01-05T10:30:00</EndDateLocal>
<UserLoginId>cm@example.com</UserLoginId>
<DateModifiedUtc>2014-12-23T11:10:00</DateModifiedUtc>
<id>https://www.concursolutions.com/api/travel/trip/
v1.1/I2uwiJJw8r7OwCIQOb2SHTsozwBsSie9W</id>
</ItineraryInfo>
</ItineraryInfoList>
Example 3: Get Trip Summary by Created Date
This requests returns trip summaries created after the specified date.
Request
GET /api/travel/trip/v1.1/?createdAfterDate=2015%2F02%2F13 HTTP/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Response
HTTP/1.1 200 OK
Content-Type: application/xml
...
<?xml version="1.0" encoding="utf-8"?>
<ItineraryInfoList xmlns="http://www.concursolutions.com/api/travel/trip/2010/06" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<ItineraryInfo>
<TripId>BWjCIJJw8r7OwCIQOb2SHTsozwBsWlSie9</TripId>
<TripName>Trip by air from Los Angeles to Mexico City</TripName>
<StartDateLocal>2015-03-09T18:45:00</StartDateLocal>
<EndDateLocal>2015-03-30T08:00:00</EndDateLocal>
<UserLoginId>cm@example.com</UserLoginId>
<DateModifiedUtc>2015-01-28T09:30:00</DateModifiedUtc>
<id>https://www.concursolutions.com/api/travel/trip/
v1.1/BWjCIJJw8r7OwCIQOb2SHTsozwBsWlSie9</id>
</ItineraryInfo>
</ItineraryInfoList>
Example 4: Get Trip Summary with Paging
This request is used for dividing the response into pages for easier processing.
Request
GET /api/travel/trip/v1.1/?createdAfterDate=2012%2F02%2F01&includeMetadata=true&ItemsPerPage=2&Page=1 HTTP/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Response
The response returns a ConnectResponse parent element which contains a MetaData element with paging information and a Data element with an ItineraryInfoList child element.
HTTP/1.1 200 OK
Content-Type: application/xml
...
<ConnectResponse>
<Metadata>
<Paging>
<TotalPages>38</TotalPages>
<TotalItems>187</TotalItems>
<CurrentPage>2</CurrentPage>
<ItemsPerPage>2</ItemsPerPage>
<PreviousPageURL>https://www.concursolutions.com/api/travel/trip/v1.1/?
createdAfterDate=2012%2F02%2F01&
itemsPerPage=5&page=3&includeMetaData=true</PreviousPageURL>
<NextPageURL>https://www.concursolutions.com/api/travel/trip/v1.1/?
createdAfterDate=2012%2F02%2F01&
itemsPerPage=5&page=1&includeMetaData=true</NextPageURL>
</Paging>
</Metadata>
<Data>
<ItineraryInfoList xmlns="http://www.concursolutions.com/api/travel/trip/2010/06" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<ItineraryInfo>
<TripId>naIzQJ0y2DBWjCIQOb2SHTsozwBsHDkdP</TripId>
<TripName>Trip from Baltimore to New York</TripName>
<StartDateLocal>2012-02-15T09:00:00</StartDateLocal>
<EndDateLocal>2012-02-21T17:30:00</EndDateLocal>
<UserLoginId>cm@example.com</UserLoginId>
<DateModifiedUtc>2012-02-14T17:13:07</DateModifiedUtc>
<id>https://www.concursolutions.com/api/travel/trip/v1.1/naIzQJ0y2DBWjCIQOb2SHTsozwBsHDkdP</id>
</ItineraryInfo>
<ItineraryInfo>
<TripId>I2uwiJJw8r7Owl3IWlSie9WIelxhAhwiL</TripId>
<TripName>Trip from Baltimore to Seattle</TripName>
<StartDateLocal>2012-03-26T09:00:00</StartDateLocal>
<EndDateLocal>2012-03-29T17:30:00</EndDateLocal>
<DateModifiedUtc>2012-03-24T19:00:00</DateModifiedUtc>
<UserLoginId>cm@example.com</UserLoginId>
<id>https://www.concursolutions.com/api/travel/trip/v1.1/I2uwiJJw8r7Owl3IWlSie9WIelxhAhwiL</id>
</ItineraryInfo>
</ItineraryInfoList>
</Data>
</ConnectResponse>
Get Trip Details
The Get Itinerary Details endpoint is used for getting details for the specified trip. The elements included in the response vary as follows:
- Some elements, such as
AirlineTicketsorRailPayments, appear only for bookings of the appropriate type. For exampleAirlineTicketsappears in the response only for air bookings andRailPayments, for rail bookings. - Amount values, such as Rate or Tax, appear only if the requestor is the source of the booking. All other suppliers will not receive the amount elements associated with the bookings.
- Some elements, such as
SabreDKNumber, appear only if the booking was created by the relevant GDS. - Some elements are vendor-specific and appear only in responses for the associated vendor.
This topic describes the full set of possible elements that can be returned. No itinerary can contain all of the possible elements, so the response will always be a subset of all the possible returned values.
By default, when calling this API, the SAP Concur account associated with the OAuth access token used to make the API call should be the owner of the trip. This endpoint can also be used to get details for trips that the OAuth consumer does not own. This is most often done when a TMC needs to get trip details on behalf of a user. The TMC must be registered with SAP Concur and have an SAP Concur account that has one of the following user roles: Web Services Administrator for Professional, or Can Administer for Standard.
Request
GET /travel/trip/v1.1/trip_ID?[systemFormat=system_format|&userid_type=login|&user_id=login_ID]
Path Parameters
| Parameter Name | Data Type | Description |
|---|---|---|
trip_ID |
string |
Required: The identifier for the desired trip. This identifier is returned as the value of the ID element when getting trip summaries. For example, if the returned value of the ID element is I2uwiJJw8r7Owl3IWlSie9WIelxhAhwiL, then the URI for the request is /travel/trip/v1.1/I2uwiJJw8r7Owl3IWlSie9WIelxhAhwi. |
Query Parameters
| Parameter Name | Data Type | Description |
|---|---|---|
systemFormat |
string |
Optional: Format of the response for a different system. The supported value is Tripit. The format for the request URI using this query parameter is /travel/trip/v1.1/trip_ID?systemFormat=Tripit. |
userid_type |
string |
Optional: The type of user identification to use. Possible value is: login. |
userid_value |
string |
Optional: The user's login ID. This parameter must be provided in conjunction with the userid_type parameter. The userid_type and userid_value parameters can only be used if the user account associated with the OAuth 2.0 access token must have an SAP Concur account with one of these roles: Web Services Administrator for Professional or Can Administer for Standard. The format for the request URI using the userid_type and userid_value query parameters is /travel/trip/v1.1/trip_ID?userid_type=login&userid_value=login_ID. |
Headers
Authorization Header (Required)
Authorization: OAuth {access_token}
Where access_token is the OAuth 2.0 access token of the user whose itinerary information you want to retrieve. If you want to access company-wide itinerary information, the user account associated with the OAuth 2.0 access token must have an SAP Concur account with one of these roles: Web Services Administrator for Professional or Can Administer for Standard.
Accept Header (Optional)
application/xml
Get Trip Details Response Schema
The response returns subset of the elements described in the following tables depending on the parameters used in the request and the status and details for the itinerary. The response can be formatted for TripIt, using the systemformat query string.
Parent Elements
| Element Name | Data Type | Description |
|---|---|---|
id |
string |
Trip ID URI with encrypted ID. |
ItinLocator |
string |
The itinerary locator. This element is now deprecated and only supported for backward compatibility. |
ClientLocator |
string |
Represents the unique identifier of the trip in an external (non-Concur) system. Maximum length 32 characters. |
ItinSourceName |
string |
The itinerary source. Format: TravelSupplier. |
TripName |
string |
Name of the trip. Maximum length 255 characters. |
Comments |
string |
Comments for this itinerary. Maximum length 512 characters. |
StartDateLocal |
dateTime |
The start date of the trip in the starting location’s timezone. Format: YYYY-MM-DDThh:mm:ss. |
EndDateLocal |
dateTime |
The end date of the trip in the ending location’s timezone. Format: YYYY-MM-DDThh:mm:ss. |
DateCreatedUtc |
dateTime |
The date that this trip was created, in UTC. Format: YYYY-MM-DDThh:mm:ss. |
DateModifiedUtc |
dateTime |
The UTC date that this trip was last modified. Format: YYYY-MM-DDThh:mm:ss. |
BookedVia |
string |
The booking method for the trip. |
BookedByFirstName |
string |
The first name of the person who booked the trip. |
BookedByLastName |
string |
The last name of the person who booked the trip. |
DateBookedLocal |
dateTime |
The date the trip was booked, in the local time of the booking location. Format: YYYY-MM-DDThh:mm:ss. |
CancelComments |
string |
The comments provided if the itinerary is cancelled. Maximum length: 256 characters. |
Description |
string |
The trip description. Maximum length: 512 characters. |
EndDateUtc |
dateTime |
The end date of the trip, in UTC. Format: YYYY-MM-DDThh:mm:ss. |
IsPersonal |
boolean |
Whether the trip is a Business or Leisure trip. Format: true/false. |
ProjectName |
string |
The associated project name for the trip. Maximum length: 255 characters. |
StartDateUtc |
dateTime |
The start date of the trip, in UTC. Format: YYYY-MM-DDThh:mm:ss. |
RuleViolations |
array |
The list of rule violations associated with the itinerary. This parent element contains a RuleViolation child element for each associated rule violation. |
Status |
string |
The status of the itinerary. One of the following: 0- Confirmed; 1- Ticketed by agent; 2- Canceled. |
Bookings |
array |
A parent element that contains a Booking child element for each booking associated with this itinerary. |
Booking Element
| Element Name | Data Type | Description |
|---|---|---|
Segments |
array |
List of segments in this booking. The child elements included in this element vary depending on whether a TMC, SAP Concur client, third-party developer, or TripLink supplier is requesting the itinerary details: For TMCs, clients, and third-party developers, the Segments element contains one or more Air, Car, Hotel, Dining, Ride, Rail, Parking, or Travel parent elements. For TripLink suppliers, the Segments element contains one or more Air, Car, Hotel, or Ride parent elements. |
Passengers |
array |
Contains a Passenger child element for each included passenger. For more information on the Passengers element, see Create a New Trip. |
RecordLocator |
string |
The unique identifier for a booking. This is often six alphanumeric characters, but can have other formats depending on the booking source. |
BookingSource |
string |
The name of the booking source for this booking. A booking source is a textual name the system uses to track where a booking took place. |
DateModifiedUtc |
dateTime |
The date the booking was last modified, in UTC. Format: YYYY-MM-DDThh:mm:ss. |
DateBookedLocal |
dateTime |
The date the booking was created, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss. |
ItinSourceName |
string |
The itinerary source. Format: TravelSupplier. |
PassengerCount |
integer |
The number of passengers included in the booking. |
Examples
Example 1: Get Trip Details for a Trip ID
Request
GET /api/travel/trip/v1.1/CNQR1234567890 HTTP/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
...
Response
HTTP/1.1 200 OK
Content-Type: application/xml
...
<?xml version="1.0" encoding="utf-8"?>
<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
<id>https://www.concursolutions.com/api/travel/trip/v1.1/CNQR1234567890</id>
<ItinLocator>CNQR1234567890</ItinLocator>
<ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
<ItinSourceName>ConcurTravel</ItinSourceName>
<TripName>Trip from Dallas to Seattle</TripName>
<Comments />
<StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<BookedVia>EveryGDS</BookedVia>
<BookedByFirstName>Chris</BookedByFirstName>
<BookedByLastName>Miller</BookedByLastName>
<DateBookedLocal>2012-07-24T19:15:52</DateBookedLocal>
<Bookings>
<Booking>
<Segments>
<Car>
<Vendor>CQ</Vendor>
<Status>HK</Status>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
<ConfirmationNumber>F1672664579</ConfirmationNumber>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<StartCityCode>SEA</StartCityCode>
<EndCityCode>SEA</EndCityCode>
<StartLocation>SEA</StartLocation>
<EndLocation>SEA</EndLocation>
<Class>E</Class>
<Body>C</Body>
<Transmission>M</Transmission>
<AirCondition>R</AirCondition>
<NumCars>1</NumCars>
<DiscountCode>346660</DiscountCode>
<DailyRate>44.0000</DailyRate>
<TotalRate>44.0000</TotalRate>
<RateType>D</RateType>
<Currency>USD</Currency>
<Charges>
<Fixed>
<Description>Dropoff Fee</Description>
<Currency>USD</Currency>
<Amount>0.0000</Amount>
<IsPrimary>false</IsPrimary>
<SemanticsCode>DROPOFFFEE</SemanticsCode>
<SemanticsVendorType>C</SemanticsVendorType>
</Fixed>
<RateWithAllowance>
<Currency>USD</Currency>
<Amount>44.0000</Amount>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<IsPrimary>true</IsPrimary>
<SemanticsCode>DAYS</SemanticsCode>
<SemanticsVendorType>C</SemanticsVendorType>
<PerUnit>DAY</PerUnit>
<NumUnits>1.0000</NumUnits>
<AllowanceNumUnits>250.0000</AllowanceNumUnits>
<AllowanceAmount>0.2400</AllowanceAmount>
<AllowanceIsUnlimited>false</AllowanceIsUnlimited>
</RateWithAllowance>
</Charges>
</Car>
</Segments>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>C123456789</RecordLocator>
<BookingSource>ConcurCars</BookingSource>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<ItinSourceName>TravelSupplier</ItinSourceName>
<PassengerCount>1</PassengerCount>
</Booking>
<Booking>
<Segments>
<Hotel>
<Vendor>CQ</Vendor>
<Status>GK</Status>
<StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<ConfirmationNumber>3364214265</ConfirmationNumber>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<RateCode>LV4</RateCode>
<Name>CONCUR HOTEL</Name>
<HotelPropertyId>CONQ</HotelPropertyId>
<CheckinTime>00:00</CheckinTime>
<CheckoutTime>00:00</CheckoutTime>
<NumPersons>1</NumPersons>
<NumRooms>1</NumRooms>
<CancellationPolicy>Cxl 1 day prior to Arrival</CancellationPolicy>
<DailyRate>240.3500</DailyRate>
<Currency>USD</Currency>
<RoomDescription>1 KING BED ACCESSIBLE ROOM - K1RRC</RoomDescription>
<Charges>
<Rate>
<Currency>USD</Currency>
<Amount>240.3500</Amount>
<StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
<IsPrimary>false</IsPrimary>
<SemanticsCode>ROOMRATE</SemanticsCode>
<SemanticsVendorType>H</SemanticsVendorType>
<PerUnit>DAY</PerUnit>
<NumUnits>3.0000</NumUnits>
</Rate>
</Charges>
</Hotel>
</Segments>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>0987654321</RecordLocator>
<BookingSource>ConcurHotel</BookingSource>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<OriginalItinLocator>33491211</OriginalItinLocator>
<ItinSourceName>ConcurTravel</ItinSourceName>
<PassengerCount>1</PassengerCount>
</Booking>
</Bookings>
</Itinerary>
Example 2: Get Trip Details in TripIt Format
Request
GET /travel/trip/v1.1/73014481752?systemFormat=Tripit HTTP/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
...
Response
<?xml version="1.0" encoding="utf-8"?>
<Response>
<Trip>
<id>73014481752</id>
<relative_url>/api/travel/trip/v1.1/73014481752</relative_url>
<start_date>2013-08-21</start_date>
<end_date>2013-08-24</end_date>
<display_name>Strategy Team meeting</display_name>
<is_private>true</is_private>
</Trip>
<AirObject>
<booking_site_conf_num>RL10001005</booking_site_conf_num>
<booking_site_name>Concur Travel</booking_site_name>
<booking_site_phone></booking_site_phone>
<booking_site_url>https://www.concursolutions.com</booking_site_url>
<record_locator>4294993825</record_locator>
<supplier_conf_num>CN10001005</supplier_conf_num>
<supplier_contact></supplier_contact>
<supplier_email_address></supplier_email_address>
<supplier_name></supplier_name>
<supplier_phone></supplier_phone>
<supplier_url></supplier_url>
<is_purchased>1</is_purchased>
<notes></notes>
<restrictions></restrictions>
<total_cost></total_cost>
<Segment>
<StartDateTime>
<date>2013-08-21</date>
<time>07:45:00</time>
</StartDateTime>
<EndDateTime>
<date>2013-08-21</date>
<time>13:03:00</time>
</EndDateTime>
<start_airport_code>PHX</start_airport_code>
<start_gate>A11</start_gate>
<start_terminal>4</start_terminal>
<end_airport_code>ORD</end_airport_code>
<end_gate>F8</end_gate>
<end_terminal>2</end_terminal>
<marketing_airline>US</marketing_airline>
<marketing_flight_number>1</marketing_flight_number>
<aircraft>320</aircraft>
<duration></duration>
<distance>1433</distance>
<notes></notes>
<seats></seats>
<service_class>Economy</service_class>
<stops>Nonstop</stops>
</Segment>
<Segment>
<StartDateTime>
<date>2013-08-24</date>
<time>13:55:00</time>
</StartDateTime>
<EndDateTime>
<date>2013-08-24</date>
<time>16:58:00</time>
</EndDateTime>
<start_airport_code>ORD</start_airport_code>
<start_gate></start_gate>
<start_terminal></start_terminal>
<end_airport_code>PHX</end_airport_code>
<end_gate></end_gate>
<end_terminal></end_terminal>
<marketing_airline>US</marketing_airline>
<marketing_flight_number>1728</marketing_flight_number>
<aircraft>A320</aircraft>
<duration></duration>
<distance></distance>
<notes></notes>
<seats></seats>
<service_class>Economy</service_class>
<stops> stops</stops>
</Segment>
<Traveler>
<first_name>William</first_name>
<middle_name></middle_name>
<last_name>Never</last_name>
<frequent_traveler_num></frequent_traveler_num>
<frequent_traveler_supplier></frequent_traveler_supplier>
<ticket_num></ticket_num>
</Traveler>
</AirObject>
</Response>
Create a New Trip
This endpoint is used for creating a new trip. To create a new trip, the specified dates in the content body can only span the trip to be created and cannot span an existing trip. To create or update a trip on behalf of a user, the OAuth access token used to make the API call should be associated with the SAP Concur account of that user. The TripLink supplier or TMC must be registered with SAP Concur and have an SAP Concur account that has one of the following user roles: Web Services Administrator for Professional, or Can Administer for Standard.
Request
POST /travel/trip/v1.1?[userid_type=login&user_id=login_ID]
Request Parameters
| Parameter Name | Data Type | Description |
|---|---|---|
userid_type |
string |
Optional: The type of user identification to use. Possible value is: login_id. |
userid_value |
string |
Optional: The value for the user identification type. Currently the only available type is login_id so the value is the login credentials. This parameter must be provided in conjunction with the userid_type parameter. The userid_type and userid_value parameters can only be used if the user account associated with the OAuth 2.0 access token is associated with an SAP Concur account with one of these roles: Web Services Administrator for Professional or Can Administer for Standard. The format for the request URI using the userid_type and userid_value query parameters is /travel/trip/v1.1/trip_ID?userid_type=login&userid_value=login_ID. |
Headers
Authorization Header (required)
Authorization: OAuth {access_token}
Where access_token is the OAuth 2.0 access token of the user whose trip you want to create or update. If you want to access company-wide itinerary information, the user account associated with the OAuth 2.0 access token must have an SAP Concur account with one of these roles: Web Services Administrator for Professional or Can Administer for Standard.
Create New Trip Request Schema
| Element Name | Required or Optional | TripLink | Data Type | Description |
|---|---|---|---|---|
Itinerary |
required | Y | ItineraryType |
The root element for a trip. For this endpoint, it contains the following elements: ClientLocator, ItinSourceName, TripName, Comments, StartDateLocal, EndDateLocal, BookedByFirstName, BookedByLastName, Bookings. |
TripName |
required | Y | string |
Name of the trip. Maximum length: 255 characters. |
TripStatus |
required | Y | unsignedByte |
The status of the trip. One of the following: 0 - Confirmed; 1 - Ticketed; 2 - Canceled; 6 - Proposal; 7 - Booked Proposal. This element only appears if the includeCanceledTrips query parameter is used in the request. |
RecordLocator |
required | Y | string |
The unique identifier for a booking. This is often six alphanumeric characters, but can have other formats depending on the booking source. |
BookingSource |
required | Y | string |
The name of the booking source for this booking. A booking source is a textual name the system uses to track where a booking took place. This could be a GDS, OTA, Vendor code for a Supplier website, or Supplier Direct Connect API. For TripLink suppliers, this is the supplier's name. |
StartDateLocal |
optional | Y | dateTime |
The start date of the trip in the starting location’s timezone. Format: YYYY-MM-DDThh:mm:ss. |
EndDateLocal |
optional | Y | dateTime |
The end date of the trip in the ending location’s timezone. Format: YYYY-MM-DDThh:mm:ss. |
BookedByFirstName |
optional | Y | string |
The first name of the person who booked the trip. |
BookedByLastName |
optional | Y | string |
The last name of the person who booked the trip. |
Bookings |
optional | Y | array |
A parent element that contains a Booking child element for each booking associated with this itinerary. |
Booking |
optional | Y | array |
A child element of the Bookings element which in turn contains the following child elements: Segments, Passengers, RecordLocator, BookingSource, DateModifiedUtc, DateBookedLocal, ItinSourceName, and PassengerCount. |
Segments |
optional | Y | array |
List of segments in this booking. The child elements included in this element vary depending on whether a TMC, client, third-party developer, or TripLink supplier is requesting the itinerary details: For TMCs, clients, and third-party developers, the Segments element contains one or more Air, Car, Hotel, Dining, Ride, Rail, Parking, or Travel parent elements. For TripLink suppliers, the Segments element contains one or more Air, Car, Hotel, or Ride parent elements. |
Comments |
optional | Y | string |
Comments for the itinerary. Maximum length: 512 characters. |
ItinSourceName |
optional | N | string |
The itinerary source. Format: TravelSupplier. |
BookingOwner |
optional | Y | string |
Indicates the tool that supplied the booking to Concur Travel. |
Source |
optional | N/A | string |
This element is obsolete. It is supported for backward compatibility only. |
DateBookedLocal |
optional | Y | dateTime |
The date the booking was created, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss. |
FormOfPaymentName |
optional | - | string |
The name of the form of payment for the booking. |
FormOfPaymentType |
optional | - | string |
The type of the form of payment. |
TicketMailingAddress |
optional | - | - | The mailing address for the booked ticket, if available. |
TicketPickupLocation |
optional | - | - | The pickup location for the booked ticket, if available. |
TicketPickupNumber |
optional | - | - | The confirmation number for the booked ticket, if available. |
AirfareQuotes |
optional | - | array |
List of stored airfare quotes for this booking. |
Airline Tickets |
optional | - | array |
List of airline tickets for this booking. |
Charges |
optional | - | array |
List of charges for this booking. |
MiscChargeOrders |
optional | - | array |
List of miscellaneous air charges for this booking. |
Passengers |
optional | Y | array |
Contains a Passenger child element for each included passenger. The Passenger child element in turn contains the following required child elements: NameFirst, NameLast, and the following optional elements: NameMiddle, NamePrefix, NameRemark, NameSuffix, NameTitle, TextName, and FrequentTravelerProgram. |
PassPrograms |
optional | - | array |
List of pass programs for this booking. This parent element has a PassProgram child element for each pass program associated with the booking. The PassProgram parent element has the following child elements: Amount, Name, Type, UserFirstName, and UserLastname. |
PhoneNumbers |
optional | - | array |
List of phone numbers associated with this booking. This parent element has a PhoneNumberData child element for each phone number associated with the booking. The PhoneNumberData parent element has the following child elements: PassengerRPH, PhoneNumber, Type, and Description. |
RailPayments |
optional | - | array |
List of rail payments associated with rail segments in this booking. It has the following child elements: RailPayment that represents the payment information for a rail booking and RailAdjustment for the amount adjusted for a rail booking. |
Segments |
optional | Y | array |
List of segments in this booking. The child elements included in this element vary depending on whether a TMC, client, third-party developer, or TripLink supplier is requesting the itinerary details: For TMCs, clients, and third-party developers, the Segments element contains one or more Air, Car, Hotel, Dining, Ride, Rail, Parking, or Travel parent elements. For TripLink suppliers, the Segments element contains one or more Air, Car, Hotel, or Ride parent elements. |
Delivery |
optional | - | - | The method this booking was delivered. |
WaitListSegments |
optional | - | - | The segments that the traveler is waitlisted for this booking. |
Warning |
optional | - | - | The warnings associated with the booking. |
WebAddresses |
optional | - | - | List of web addresses such as emails, pick-up URLs, and so on associated with this booking. |
Create New Trip Response Schema
The response returns an HTTP status code and if the trip is created successfully, it also returns the full posted trip details with the following additional elements inside the Itinerary parent element:
| Element Name | Data Type | TripLink | Description |
|---|---|---|---|
id |
string |
Y | The URI including the trip ID. |
ItinLocator |
string |
Y | The Itinerary Locator value (trip ID without the URL). The ItinLocator value is used when updating an existing trip. |
DateModifiedUtc |
dateTime |
Y | The UTC formatted date that this booking was last modified. |
BookedVia |
string |
Y | The booking method or the GDS the itinerary was booked in. |
DateBookedLocal |
dateTime |
Y | The date, in the traveler’s local time, that the booking was made. |
Examples
Example 1: TMC Creates a Trip for User Using Their Login Credentials
This example shows how to create a trip for a user using their login credentials.
Request
POST /api/travel/trip/v1.1?userid_type=login_id&userid_value=cm@example.com HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Content-Type: application/xml
...
<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
<ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
<ItinSourceName>ConcurConnectAPI</ItinSourceName>
<TripName>Trip from Dallas to Seattle</TripName>
<Comments />
<StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<BookedByFirstName>Chris</BookedByFirstName>
<BookedByLastName>Miller</BookedByLastName>
<Bookings>
<Booking>
<Segments>
<Car>
<Vendor>CQ</Vendor>
<Status>HK</Status>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
<ConfirmationNumber>F1672664579</ConfirmationNumber>
<StartCityCode>SEA</StartCityCode>
<EndCityCode>SEA</EndCityCode>
<StartLocation>SEA</StartLocation>
<EndLocation>SEA</EndLocation>
<Class>E</Class>
<Body>C</Body>
<Transmission>M</Transmission>
<AirCondition>R</AirCondition>
<NumCars>1</NumCars>
<DiscountCode>346660</DiscountCode>
<DailyRate>44.0000</DailyRate>
<TotalRate>44.0000</TotalRate>
<RateType>D</RateType>
<Currency>USD</Currency>
<Charges>
<Fixed>
<Description>Dropoff Fee</Description>
<Currency>USD</Currency>
<Amount>0.0000</Amount>
<IsPrimary>false</IsPrimary>
<SemanticsCode>DROPOFFFEE</SemanticsCode>
<SemanticsVendorType>C</SemanticsVendorType>
</Fixed>
<RateWithAllowance>
<Currency>USD</Currency>
<Amount>44.0000</Amount>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<IsPrimary>true</IsPrimary>
<SemanticsCode>DAYS</SemanticsCode>
<SemanticsVendorType>C</SemanticsVendorType>
<PerUnit>DAY</PerUnit>
<NumUnits>1.0000</NumUnits>
<AllowanceNumUnits>250.0000</AllowanceNumUnits>
<AllowanceAmount>0.2400</AllowanceAmount>
<AllowanceIsUnlimited>false</AllowanceIsUnlimited>
</RateWithAllowance>
</Charges>
</Car>
</Segments>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>C123456789</RecordLocator>
<BookingSource>TravelBookings.com</BookingSource>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<ItinSourceName>ConcurConnectAPI</ItinSourceName>
<PassengerCount>1</PassengerCount>
</Booking>
<Booking>
<Segments>
<Hotel>
<Vendor>CQ</Vendor>
<Status>GK</Status>
<StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<ConfirmationNumber>3364214265</ConfirmationNumber>
<RateCode>LV4</RateCode>
<Name>CONCUR HOTEL</Name>
<HotelPropertyId>CONQ</HotelPropertyId>
<CheckinTime>03:00 PM</CheckinTime>
<CheckoutTime>12:00 PM</CheckoutTime>
<NumPersons>1</NumPersons>
<NumRooms>1</NumRooms>
<CancellationPolicy>Cxl 1 day prior to Arrival</CancellationPolicy>
<DailyRate>240.3500</DailyRate>
<Currency>USD</Currency>
<RoomDescription>1 KING BED ACCESSIBLE ROOM - K1RRC</RoomDescription>
<Charges>
<Rate>
<Currency>USD</Currency>
<Amount>240.3500</Amount>
<StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
<IsPrimary>false</IsPrimary>
<SemanticsCode>ROOMRATE</SemanticsCode>
<SemanticsVendorType>H</SemanticsVendorType>
<PerUnit>DAY</PerUnit>
<NumUnits>3.0000</NumUnits>
</Rate>
</Charges>
</Hotel>
</Segments>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>0987654321</RecordLocator>
<BookingSource>TravelBookings.com</BookingSource>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<OriginalItinLocator>33491211</OriginalItinLocator>
<ItinSourceName>ConcurConnectAPI</ItinSourceName>
<PassengerCount>1</PassengerCount>
</Booking>
</Bookings>
</Itinerary>
Response
<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
<id>https://www.concursolutions.com/api/travel/trip/v1.1/CNQR1234567890</id>
<ItinLocator>CNQR1234567890</ItinLocator>
<ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
<ItinSourceName>ConcurTravel</ItinSourceName>
<TripName>Trip from Dallas to Seattle</TripName>
<Comments />
<StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<BookedVia>EveryGDS</BookedVia>
<BookedByFirstName>Chris</BookedByFirstName>
<BookedByLastName>Miller</BookedByLastName>
<DateBookedLocal>2012-07-24T19:15:52</DateBookedLocal>
<Bookings>
<Booking>
<Segments>
<Car>
<Vendor>CQ</Vendor>
<Status>HK</Status>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
<ConfirmationNumber>F1672664579</ConfirmationNumber>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<StartCityCode>SEA</StartCityCode>
<EndCityCode>SEA</EndCityCode>
<StartLocation>SEA</StartLocation>
<EndLocation>SEA</EndLocation>
<Class>E</Class>
<Body>C</Body>
<Transmission>M</Transmission>
<AirCondition>R</AirCondition>
<NumCars>1</NumCars>
<DiscountCode>346660</DiscountCode>
<DailyRate>44.0000</DailyRate>
<TotalRate>44.0000</TotalRate>
<RateType>D</RateType>
<Currency>USD</Currency>
<Charges>
<Fixed>
<Description>Dropoff Fee</Description>
<Currency>USD</Currency>
<Amount>0.0000</Amount>
<IsPrimary>false</IsPrimary>
<SemanticsCode>DROPOFFFEE</SemanticsCode>
<SemanticsVendorType>C</SemanticsVendorType>
</Fixed>
<RateWithAllowance>
<Currency>USD</Currency>
<Amount>44.0000</Amount>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<IsPrimary>true</IsPrimary>
<SemanticsCode>DAYS</SemanticsCode>
<SemanticsVendorType>C</SemanticsVendorType>
<PerUnit>DAY</PerUnit>
<NumUnits>1.0000</NumUnits>
<AllowanceNumUnits>250.0000</AllowanceNumUnits>
<AllowanceAmount>0.2400</AllowanceAmount>
<AllowanceIsUnlimited>false</AllowanceIsUnlimited>
</RateWithAllowance>
</Charges>
</Car>
</Segments>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>C123456789</RecordLocator>
<BookingSource>ConcurCars</BookingSource>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<ItinSourceName>TravelSupplier</ItinSourceName>
<PassengerCount>1</PassengerCount>
</Booking>
<Booking>
<Segments>
<Hotel>
<Vendor>CQ</Vendor>
<Status>GK</Status>
<StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<ConfirmationNumber>3364214265</ConfirmationNumber>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<RateCode>LV4</RateCode>
<Name>CONCUR HOTEL</Name>
<HotelPropertyId>CONQ</HotelPropertyId>
<CheckinTime>00:00</CheckinTime>
<CheckoutTime>00:00</CheckoutTime>
<NumPersons>1</NumPersons>
<NumRooms>1</NumRooms>
<CancellationPolicy>Cxl 1 day prior to Arrival</CancellationPolicy>
<DailyRate>240.3500</DailyRate>
<Currency>USD</Currency>
<RoomDescription>1 KING BED ACCESSIBLE ROOM - K1RRC</RoomDescription>
<Charges>
<Rate>
<Currency>USD</Currency>
<Amount>240.3500</Amount>
<StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
<IsPrimary>false</IsPrimary>
<SemanticsCode>ROOMRATE</SemanticsCode>
<SemanticsVendorType>H</SemanticsVendorType>
<PerUnit>DAY</PerUnit>
<NumUnits>3.0000</NumUnits>
</Rate>
</Charges>
</Hotel>
</Segments>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>0987654321</RecordLocator>
<BookingSource>ConcurHotel</BookingSource>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<OriginalItinLocator>33491211</OriginalItinLocator>
<ItinSourceName>ConcurTravel</ItinSourceName>
<PassengerCount>1</PassengerCount>
</Booking>
</Bookings>
</Itinerary>
Example 2: TripLink Supplier Creates a Trip
This example shows how a TripLink supplier creates a trip.
Request
POST /api/travel/trip/v1.1/ HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Content-Type: application/xml
...
<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
<TripName>Trip from Dallas to Seattle</TripName>
<TripStatus>HK</TripStatus>
<Comments />
<StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<BookedByFirstName>Chris</BookedByFirstName>
<BookedByLastName>Miller</BookedByLastName>
<Bookings>
<Booking>
<Segments>
<Car>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
<StartCityCode>SEA</StartCityCode>
<EndCityCode>SEA</EndCityCode>
</Car>
</Segments>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>C123456789</RecordLocator>
<BookingSource>TravelBookings.com</BookingSource>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
</Booking>
<Booking>
<Segments>
<Hotel>
<Status>GK</Status>
<StartCityCode>SEA</StartCityCode>
<StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<TimeZoneId>Pacific</TimeZoneId>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<StartCity>Seattle</StartCity>
<StartCountry>US</StartCountry>
</Hotel>
</Segments>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>0987654321</RecordLocator>
<BookingSource>TravelBookings.com</BookingSource>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
</Booking>
</Bookings>
</Itinerary>
Response
<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
<id>https://www.concursolutions.com/api/travel/trip/v1.1/CNQR1234567890</id>
<ItinLocator>CNQR1234567890</ItinLocator>
<TripName>Trip from Dallas to Seattle</TripName>
<TripStatus>HK</TripStatus>
<Comments />
<StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<BookedVia>EveryGDS</BookedVia>
<BookedByFirstName>Chris</BookedByFirstName>
<BookedByLastName>Miller</BookedByLastName>
<DateBookedLocal>2012-07-24T19:15:52</DateBookedLocal>
<Bookings>
<Booking>
<Segments>
<Car>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
<StartCityCode>SEA</StartCityCode>
<EndCityCode>SEA</EndCityCode>
</Car>
</Segments>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>C123456789</RecordLocator>
<BookingSource>TravelBookings.com</BookingSource>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
</Booking>
<Booking>
<Segments>
<Hotel>
<Status>GK</Status>
<StartCityCode>SEA</StartCityCode>
<StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<TimeZoneId>Pacific</TimeZoneId>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<StartCity>Seattle</StartCity>
<StartCountry>US</StartCountry>
</Hotel>
</Segments>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>0987654321</RecordLocator>
<BookingSource>TravelBookings.com</BookingSource>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
</Booking>
</Bookings>
</Itinerary>
Example 3: Third-Party Developer Creates a Trip Using the Access Token Used to Make the API Call
This example shows how to create a trip for a user whose account is associated with the access token used to make the API call.
Request
POST https://www.concursolutions.com/api/travel/trip/v1.1 HTTPS/1.1
Authorization: OAuth {access token}
Content-Type: application/xml
...
<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
<ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
<ItinSourceName>ConcurConnectAPI</ItinSourceName>
<TripName>Trip from Dallas to Seattle</TripName>
<Comments />
<StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<BookedByFirstName>Chris</BookedByFirstName>
<BookedByLastName>Miller</BookedByLastName>
<TripStatus>7</TripStatus>
<TravelRequestId>3339</TravelRequestId>
<CustomAttributes>
<CustomAttribute>
<ExternalId />
<DataType>Numeric</DataType>
<Name>ProposalBatchSize</Name>
<DisplayTitle />
<Data>3</Data>
<DisplayOnItinerary>true</DisplayOnItinerary>
</CustomAttribute>
<CustomAttribute>
<ExternalId />
<DataType>Numeric</DataType>
<Name>ProposalSequenceIndex</Name>
<DisplayTitle />
<Data>1</Data>
<DisplayOnItinerary>true</DisplayOnItinerary>
</CustomAttribute>
</CustomAttributes>
<Bookings>
<Booking>
<Segments>
<Car>
<Vendor>CQ</Vendor>
<Status>HK</Status>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
<ConfirmationNumber>F1672664579</ConfirmationNumber>
<StartCityCode>SEA</StartCityCode>
<EndCityCode>SEA</EndCityCode>
<StartLocation>SEA</StartLocation>
<EndLocation>SEA</EndLocation>
<Class>E</Class>
<Body>C</Body>
<Transmission>M</Transmission>
<AirCondition>R</AirCondition>
<NumCars>1</NumCars>
<DiscountCode>346660</DiscountCode>
<DailyRate>44.0000</DailyRate>
<TotalRate>44.0000</TotalRate>
<RateType>D</RateType>
<Currency>USD</Currency>
<Charges>
<Fixed>
<Description>Dropoff Fee</Description>
<Currency>USD</Currency>
<Amount>0.0000</Amount>
<IsPrimary>false</IsPrimary>
<SemanticsCode>DROPOFFFEE</SemanticsCode>
<SemanticsVendorType>C</SemanticsVendorType>
</Fixed>
<RateWithAllowance>
<Currency>USD</Currency>
<Amount>44.0000</Amount>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<IsPrimary>true</IsPrimary>
<SemanticsCode>DAYS</SemanticsCode>
<SemanticsVendorType>C</SemanticsVendorType>
<PerUnit>DAY</PerUnit>
<NumUnits>1.0000</NumUnits>
<AllowanceNumUnits>250.0000</AllowanceNumUnits>
<AllowanceAmount>0.2400</AllowanceAmount>
<AllowanceIsUnlimited>false</AllowanceIsUnlimited>
</RateWithAllowance>
</Charges>
</Car>
</Segments>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>C123456789</RecordLocator>
<BookingSource>TravelBookings.com</BookingSource>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<ItinSourceName>ConcurConnectAPI</ItinSourceName>
<PassengerCount>1</PassengerCount>
</Booking>
<Booking>
<Segments>
<Hotel>
<Vendor>CQ</Vendor>
<Status>GK</Status>
<StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<ConfirmationNumber>3364214265</ConfirmationNumber>
<RateCode>LV4</RateCode>
<Name>CONCUR HOTEL</Name>
<HotelPropertyId>CONQ</HotelPropertyId>
<CheckinTime>03:00 PM</CheckinTime>
<CheckoutTime>12:00 PM</CheckoutTime>
<NumPersons>1</NumPersons>
<NumRooms>1</NumRooms>
<CancellationPolicy>Cxl 1 day prior to Arrival</CancellationPolicy>
<DailyRate>240.3500</DailyRate>
<Currency>USD</Currency>
<RoomDescription>1 KING BED ACCESSIBLE ROOM - K1RRC</RoomDescription>
<Charges>
<Rate>
<Currency>USD</Currency>
<Amount>240.3500</Amount>
<StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
<IsPrimary>false</IsPrimary>
<SemanticsCode>ROOMRATE</SemanticsCode>
<SemanticsVendorType>H</SemanticsVendorType>
<PerUnit>DAY</PerUnit>
<NumUnits>3.0000</NumUnits>
</Rate>
</Charges>
</Hotel>
</Segments>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>0987654321</RecordLocator>
<BookingSource>TravelBookings.com</BookingSource>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<OriginalItinLocator>33491211</OriginalItinLocator>
<ItinSourceName>ConcurConnectAPI</ItinSourceName>
<PassengerCount>1</PassengerCount>
</Booking>
</Bookings>
</Itinerary>
Response
The response is the same as in Example 1.
Update a Trip
Creates a new trip or updates an existing trip. A new trip will be created if the trip dates span no existing trip and the request doesn’t include a tripId. If a tripId is included in the URI it will update the specified trip. The full trip information is included in the update request, which replaces the existing trip.
This endpoint can be used to create trips for a user that is not the OAuth consumer. This is most often done when a travel supplier or TMC needs to create a trip on behalf of a user. The supplier or TMC must be registered with SAP Concur and have an SAP Concur account that has one of the following user roles: Web Services Administrator for Professional, or Can Administer for Standard.
Cancel a Trip
This endpoint can be used to cancel all segments in a trip. To cancel a trip on behalf of a user, the OAuth access token used to make the API call should be associated with the SAP Concur account of that user. The TripLink supplier or TMC must be registered with SAP Concur and have an SAP Concur account that has one of the following user roles: Web Services Administrator for Professional, or Can Administer for Standard.
Request
POST /travel/trip/v1.1/cancel?tripid=trip_ID[&userid_type=login&userid_value=login_ID]
Path Parameters
| Parameter Name | Data Type | Description |
|---|---|---|
cancel |
required | string |
Request Parameters
| Parameter Name | Data Type | Description |
|---|---|---|
tripid |
string |
Optional: The identifier for the trip to be updated. For example, if the value of tripid is I2uwiJJw8r7Owl3IWlSie9WIelxhAhwiL, then the request is POST /travel/trip/v1.1?tripid=I2uwiJJw8r7Owl3IWlSie9WIelxhAhwiL. |
userid_type |
string |
Optional: The type of user identification to use. Possible value is: login_id. |
userid_value |
string |
Optional: The user's login ID. This parameter must be provided in conjunction with the userid_type parameter. The userid_type and userid_value parameters can only be used if the user account associated with the OAuth 2.0 access token must have an SAP Concur account with one of these roles: Web Services Administrator for Professional or Can Administer for Standard. The format for the request URI using the userid_type and userid_value query parameters is /travel/trip/v1.1/trip_ID?userid_type=login&userid_value=login_ID. |
Headers
Authorization Header (Required)
Authorization: OAuth {access_token}
Where access_token is the OAuth 2.0 access token of the user whose trip you want to create or update. If you want to access company-wide itinerary information, the user account associated with the OAuth 2.0 access token must have an SAP Concur account with one of these roles: Web Services Administrator for Professional or Can Administer for Standard.
Request Content Body
None.
Cancel Trip Request Schema
The request returns the full trip details for the cancelled trip. If the request is successful, the response trip will not contain any segments because they have been cancelled. The response includes the following additional elements inside the Itinerary parent element:
| Parameter Name | Data Type | Description |
|---|---|---|
id |
string |
The URI including the trip ID. |
ItinLocator |
string |
The itinerary locator value (trip ID without the URL). The ItinLocator value is used when updating an existing trip. |
DateModifiedUtc |
dateTime |
The UTC formatted date that this booking was last modified. |
BookedVia |
string |
The GDS the itinerary was booked in. |
DateBookedLocal |
dateTime |
The date, in the traveler’s local time, that the booking was made. |
Examples
Example: Cancel a Trip with a Specific Trip ID
Request
POST /api/travel/trip/v1.1/cancel?tripId=CNQR1234567890 HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
...
Response
<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
<id>https://www.concursolutions.com/api/travel/trip/v1.1/CNQR1234567890</id>
<ItinLocator>CNQR1234567890</ItinLocator>
<ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
<ItinSourceName>ConcurTravel</ItinSourceName>
<TripName>Trip from Dallas to Seattle</TripName>
<Comments />
<StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<BookedVia>EveryGDS</BookedVia>
<BookedByFirstName>Chris</BookedByFirstName>
<BookedByLastName>Miller</BookedByLastName>
<DateBookedLocal>2012-07-24T19:15:52</DateBookedLocal>
<Bookings>
<Booking>
<Segments/>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>C123456789</RecordLocator>
<BookingSource>ConcurCars</BookingSource>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<ItinSourceName>TravelSupplier</ItinSourceName>
<PassengerCount>1</PassengerCount>
</Booking>
<Booking>
<Segments/>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>0987654321</RecordLocator>
<BookingSource>ConcurHotel</BookingSource>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<OriginalItinLocator>33491211</OriginalItinLocator>
<ItinSourceName>ConcurTravel</ItinSourceName>
<PassengerCount>1</PassengerCount>
</Booking>
</Bookings>
</Itinerary>
USER-PROVISIONING
Spend User v4 - Getting Started
Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.
Spend User Provisioning allows callers to provision a user in the SAP Concur spend domain. This is an asynchronous downstream process from the User Provisioning v4 service. Currently spend user data can be created, modified, and replaced with the POST, PATCH, and PUT provisioning operations. The retrieval of spend user data is supported through GET endpoints: One that can retrieve a filtered and paginated set of all spend users in a company, and another that can retrieve a specific spend user's data using their unique identifier.
Limitations: This API is only available to partners who have been granted access. Access to this documentation does not provide access to the API.
Getting Started
Products and Editions
- Concur Expense Professional Edition
- Concur Expense Standard Edition
- Concur Invoice Professional Edition
- Concur Invoice Standard Edition
- Concur Request Professional Edition
- Concur Request Standard Edition
Scope Usage
| Name | Description | Endpoint |
|---|---|---|
spend.user.general.read |
View spend user information. | GET |
spend.user.general.writeonly |
Change spend user information. | POST, PUT |
Note: In addition to the spend scopes, you will need the scopes listed in User Provisioning v4 in order to provision core user data via the /provision/v4/Bulk endpoint.
Dependencies
SAP Concur users must purchase Concur Expense in order to use the spend extensions to provision spend related data. SAP Concur clients must use the User Provisioning v4 API to provision users in order to use this endpoint to retrieve user data.
Access Token Usage
This API currently only supports company level access tokens.
User Provisioning Service
Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.
The User Provisioning Service allows callers to provision a user in the SAP Concur environment. Once a user is provisioned, the user profile is set up in Identity, Travel, and Spend.
Limitations: This API is only available to partners who have been granted access. Access to this documentation does not provide access to the API.
- Products and Editions
- Scope Usage
- Dependencies
- Access Token Usage
- Event Usage
- Create a Provisioning Request for One or More Users
- Update One or More Provisioning Requests
- Replace One or More Resources
- Create a User Provisioning Request
- Update the Identity Data of a User
- Replace a User Resource
- Retrieving User Profile Data
- Retrieve a Provisioning Request Summary Status
- Retrieve a Detailed Provisioning Request Status
- Retrieve Supported Resource Types
Process Flow

Products and Editions
- Concur Expense Professional Edition
- Concur Expense Standard Edition
- Concur Travel Professional Edition
- Concur Travel Standard Edition
- Concur Invoice Professional Edition
- Concur Invoice Standard Edition
- Concur Request Professional Edition
- Concur Request Standard Edition
Scope Usage
| Name | Description | Endpoint |
|---|---|---|
user.provision.write |
Provision a user. | GET, POST, PUT, PATCH |
user.provision.read |
Request status of a provisioning request. | GET |
identity.user.coreenterprise.writeonly |
Write access to all core and enterprise extensions except externalID. |
POST, PUT, PATCH |
identity.user.externalID.writeonly |
Write access to externalID only. |
POST, PUT, PATCH |
identity.user.ids.read |
Read user ID data. | GET |
identity.user.core.read |
Read user core data. | GET |
identity.user.coresensitive.read |
Read core sensitive data. | GET |
identity.user.enterprise.read |
Read user enterprise data. | GET |
travel.user.general.read |
Read general Travel data. | GET |
travel.user.private.read |
Read private Travel data. | GET |
spend.user.general.writeonly |
Change spend user information. | POST, PUT, PATCH |
spend.user.general.read |
View spend user information. | GET |
Dependencies
SAP Concur users must purchase either Concur Expense or Concur Travel or both in order to use this API. This API only available to approved early adopter partners and clients. Please contact your SAP Concur representative for more information.
Access Token Usage
This API supports company level access tokens.
Events
UPS supports post event notification when provisioning process is complete.
https://developer.concur.com/api-reference/callouts/post-event-notification.html
Event Type:
* ProvisioningComplete
Create a Provisioning Request for One or More Users
Creates one or more provisioning requests.
Scopes
user.provision.write- Refer to Scope Usage for full details.identity.user.coreenterprise.writeonly- Refer to Scope Usage for full details.identity.user.externalID.writeonly- Refer to Scope Usage for full details.spend.user.general.writeonly- Refer to Scope Usage for full details.
Request
POST https://www.us.api.concursolutions.com/provisioning/v4/Bulk/
URI
Template
POST /provisioning/v4/Bulk/
Parameters
None
Headers
Payload
Response
Status Codes
- 200 OK
- 201 Created
- 202 Accepted
- 400 Bad Request
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found
- 408 Request Timeout
- 413 Payload Too Large
- 429 Too Many Requests
- 500 Internal Server Error
- 501 Not Implemented
- 502 Bad Gateway
- 503 Service Unavailable
- 504 Gateway Timeout
Payload
None
Example
Request
The maximum file size allowed is 100 operations or 400kb per request.
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:BulkRequest"
],
"failOnErrors": 1,
"Operations": [
{
"method": "POST",
"path": "/Users",
"bulkId": "bulk-operation-1",
"data": {
"userName": "Chris.doe198@sap.com",
"active": true,
"name": {
"formatted": "Chris Doe",
"legalName": "Chris Doe",
"familyName": "Doe",
"givenName": "Chris"
},
"emails": [
{
"value": "Chris.doe198@sap.com",
"type": "work"
}
],
"timezone": "America/Los_Angeles",
"entitlements": [
"Expense",
"Travel"
],
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"employeeNumber": "3749",
"companyId": "xxxxxxxx-xxx-xxx-xxx-9300b1c317xxx"
}
}
}
]
}
Response
202 Accepted
Content-Type: application/json
{
"schemas": [
"urn:ietf:params:scim:schemas:extension:concur:2.0:Provision:Status"
],
"id": "9ff00c90-1c35-4fd1-8ac7-db8b9be70a98",
"operationsCount": {
"total": 1,
"success": 1,
"failed": 0,
"pending": 0
},
"status": {
"completed": false,
"success": null
},
"meta": {
"location": "https://us.api.concursolutions.com/provisioning/v4/provisions/9ff00c90-1c35-4fd1-8ac7-db8b9be70a98/status",
"created": "2021-04-26T16:29:38.459+0000",
"lastModified": "2021-04-26T16:29:38.459+0000",
"provisionType": "Bulk",
"resourceType": "ProvisionRequest",
"correlationId": "a2e9973f-516a-4203-ab86-b3d592fc0d5b"
}
}
Update One or More Provisioning Requests
Updates one or more provisioning requests.
Scopes
user.provision.write- Refer to Scope Usage for full details.identity.user.coreenterprise.writeonly- Refer to Scope Usage for full details.identity.user.externalID.writeonly- Refer to Scope Usage for full details.spend.user.general.writeonly- Refer to Scope Usage for full details.
Request
PATCH https://www.us.api.concursolutions.com/provisioning/v4/Bulk/
URI
Template
PATCH /provisioning/v4/Bulk/
Parameters
None.
Headers
Payload
Response
Status Codes
- 200 OK
- 201 Created
- 202 Accepted
- 400 Bad Request
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found
- 408 Request Timeout
- 413 Payload Too Large
- 429 Too Many Requests
- 500 Internal Server Error
- 501 Not Implemented
- 502 Bad Gateway
- 503 Service Unavailable
- 504 Gateway Timeout
Payload
None
Example
Request
PATCH https://www.us.api.concursolutions.com/provisioning/v4/Bulk/
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:BulkRequest",
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"failOnErrors": 1,
"Operations": [
{
"method": "PATCH",
"path": "/Users/8f545a90-305f-441b-91cd-a69ad5f548f5",
"data": {
"Operations": [
{
"op": "add",
"path": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department",
"value": "Engineering"
},
{
"op": "replace",
"path": "userName",
"value":
"Updated_Chris_Doe_Name@sap.com"
}
]
}
}
]
}
Response
202 Accepted
Content-Type: application/json
{
"schemas": [
"urn:ietf:params:scim:schemas:extension:concur:2.0:Provision:Status"
],
"id": "193975e3-f9b2-4786-813d-b209ee0f8527",
"operationsCount": {
"total": 1,
"success": 0,
"failed": 0,
"pending": 1
},
"status": {
"completed": true,
"success": true
},
"meta": {
"location": "https://us.api.concursolutions.com/provisioning/v4/provisions/193975e3-f9b2-4786-813d-b209ee0f8527/status",
"created": "2021-04-26T16:47:44.009+0000",
"lastModified": "2021-04-26T16:47:44.009+0000",
"provisionType": "Bulk",
"resourceType": "ProvisionRequest",
"correlationId": "96f93318-8fb1-4949-b4ed-b4316455b032"
}
}
provisionId: "193975e3-f9b2-4786-813d-b209ee0f8527" is the provisioning request ID. This is a unique number that is used for querying status on the request.location: The location to receive status on the provisioning request.
Replace One or More Resources
Replaces one or more existing resources. In the case where all attributes are not provisioned, system default values will be provisioned.
Scopes
user.provision.write- Refer to Scope Usage for full details.identity.user.coreenterprise.writeonly- Refer to Scope Usage for full details.identity.user.externalID.writeonly- - Refer to Scope Usage for full details.spend.user.general.writeonly- Refer to Scope Usage for full details.
Request
PUT https://www.us.api.concursolutions.com/provisioning/v4/Bulk/
URI
Template
PUT /provisioning/v4/Bulk/
Parameters
None.
Headers
Payload
Response
Status Codes
- 200 OK
- 201 Created
- 202 Accepted
- 400 Bad Request
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found
- 408 Request Timeout
- 413 Payload Too Large
- 429 Too Many Requests
- 500 Internal Server Error
- 501 Not Implemented
- 502 Bad Gateway
- 503 Service Unavailable
- 504 Gateway Timeout
Payload
None
Example
Request
- Note that the SAP Concur platform UUID within the id attribute and path must be included within the data of the request.
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:BulkRequest"
],
"failOnErrors": 1,
"Operations": [
{
"method": "PUT",
"path": "/Users/8f545a90-305f-441b-91cd-a69ad5f548f5",
"bulkId": "Seattle",
"data": {
"id": "8f545a90-305f-441b-91cd-a69ad5f548f5",
"userName": "john.doe21224@sap.com",
"active": false,
"name": {
"formatted": "Mr. John Doe",
"legalName": "Mr. John Doe",
"middleName": "Joe",
"middleInitial": "J",
"familyName": "Doe",
"givenName": "John",
"honorificPrefix": "Prof Dr Mr",
"honorificSuffix": "VI",
"hasNoMiddleName": true
},
"emails": [
{
"value": "john.doe193@sap.com",
"type": "work"
}
]
}
}
]
}
Response
202 Accepted
Content-Type: application/json
{
"schemas": [
"urn:ietf:params:scim:schemas:extension:concur:2.0:Provision:Status"
],
"id": "a43fd01c-fc99-4cf1-a16e-6f440b797603",
"operationsCount": {
"total": 1,
"success": 1,
"failed": 0,
"pending": 0
},
"status": {
"completed": true,
"success": true
},
"meta": {
"location": "https://us.api.concursolutions.com/provisioning/v4/provisions/a43fd01c-fc99-4cf1-a16e-6f440b797603/status",
"created": "2021-04-26T16:57:39.719+0000",
"lastModified": "2021-04-26T16:57:39.719+0000",
"provisionType": "Bulk",
"resourceType": "ProvisionRequest",
"correlationId": "dbe2c569-3662-46e7-8521-e6ba77a014ef"
}
}
provisionId: "a43fd01c-fc99-4cf1-a16e-6f440b797603" is the provisioning request ID. This is a unique number that is used for querying status on the request.location: The location to receive status on the provisioning request.
Create a User Provisioning Request
Allows the creation of a single user resource.
Scopes
user.provision.write- Refer to Scope Usage for full details.identity.user.coreenterprise.writeonly- Refer to Scope Usage for full details.identity.user.externalID.writeonly- Refer to Scope Usage for full details.spend.user.general.writeonly- Refer to Scope Usage for full details.
Request
POST https://www.us.api.concursolutions.com/provisioning/v4/Users/
URI
Template
POST /provisioning/v4/Users/
Parameters
None
Headers
Payload
Request
Status Codes
- 200 OK
- 201 Created
- 202 Accepted
- 400 Bad Request
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found
- 408 Request Timeout
- 413 Payload Too Large
- 429 Too Many Requests
- 500 Internal Server Error
- 501 Not Implemented
- 502 Bad Gateway
- 503 Service Unavailable
- 504 Gateway Timeout
Payload
None
Example
Request
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"userName": "John4_29_4@cs-sso-us-prod.com",
"active": true,
"name": {
"formatted": "Mr. John Doe",
"legalName": "Mr. John Doe",
"middleName": "Joe",
"middleInitial": "J",
"familyName": "Doe",
"givenName": "John",
"honorificPrefix": "Prof Dr Mr",
"honorificSuffix": "VI",
"hasNoMiddleName": false
},
"emails": [
{
"value": "John4_29_4@cs-sso-us-prod.com",
"type": "work"
}
],
"entitlements": [
"Expense",
"Invoice",
"Locate",
"Request",
"Travel"
],
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"employeeNumber": "John4_29_4@cs-sso-us-prod.com",
"companyId": "aa076ada-80a9-4f57-8e98-9300b1c3171d"
},
"urn:ietf:params:scim:schemas:extension:spend:2.0:User": {
"locale": "en-US",
"country": "US",
"stateProvince": "WA",
"ledgerCode": "DEFAULT",
"reimbursementCurrency": "USD",
"cashAdvanceAccountCode": "Code",
"customData": [
{
"id": "custom1",
"value": "testing"
},
{
"id": "orgUnit1",
"value": "testDepartment"
}
]
},
"urn:ietf:params:scim:schemas:extension:spend:2.0:WorkflowPreference": {
"emailStatusChangeOnCashAdvance": true,
"emailAwaitApprovalOnCashAdvance": true,
"emailStatusChangeOnReport": true,
"emailAwaitApprovalOnReport": true,
"promptForApproverOnReportSubmit": true,
"emailStatusChangeOnTravelRequest": true,
"emailAwaitApprovalOnTravelRequest": true,
"promptForApproverOnTravelRequestSubmit": true,
"emailStatusChangeOnPayment": true,
"emailAwaitApprovalOnPayment": true,
"promptForApproverOnPaymentSubmit": true,
"promptForCardTransactionsOnReport": true
},
"urn:ietf:params:scim:schemas:extension:spend:2.0:UserPreference": {
"allowCreditCardTransArrivalEmails": true,
"defaultReportPrintFormat": "DETAILED",
"showInstructHelpPanel": true,
"expenseAuditRequired": "ALWAYS",
"showImagingIntro": true,
"allowReceiptImageAvailEmails": true,
"autoAddTripCardTransOnReport": true,
"processorReportAccess": "All reports excluding returned",
"promptForCardTransactionsOnReport": true,
"promptForReportPrintFormat": true,
"showExpenseOnReport": "ALL",
"showTotalOnReport": true,
"useQuickItinAsDefault": false
},
"urn:ietf:params:scim:schemas:extension:spend:2.0:Role": {
"roles": [
{
"roleName": "EXP_APPROVER",
"roleGroups": []
}
]
},
"urn:ietf:params:scim:schemas:extension:spend:2.0:Approver": {
"report": [
{
"approver": {
"value": "d1eb15c1-ac9b-40d6-b5f7-ea2d2f5ae8a7",
"$ref": "https://www.concursoultions.com/users/approver2",
"displayName": "test.employee@sap.com",
"employeeNumber": "37480"
},
"primary": true
}
]
}
}
Response
201 Created
Content-Type: application/json
{
"meta": {
"resourceType": "User",
"created": "2021-04-26T20:07:55.000097Z",
"lastModified": "2021-04-26T20:07:55.000097Z",
"version": 0,
"location": "https://us.api.concursolutions.com/profile/identity/v4/Users/ef0bffaf-863f-4b3e-9c4c-bd9c9a8b2ea7",
"statusUrl": "https://us.api.concursolutions.com/provisioning/v4/provisions/2b41c0c1-15f7-41cc-99bb-a82b5da128a2/status",
"provisionId": "2b41c0c1-15f7-41cc-99bb-a82b5da128a2"
},
"displayName": "John",
"name": {
"middleInitial": "J",
"middleName": "Joe",
"formatted": "Doe, John Joe",
"honorificPrefix": "Prof Dr Mr",
"legalName": "Mr. John Doe",
"familyName": "Doe",
"givenName": "John",
"honorificSuffix": "VI"
},
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
"urn:ietf:params:scim:schemas:extension:sap:2.0:User"
],
"active": true,
"id": "ef0bffaf-863f-4b3e-9c4c-bd9c9a8b2ea7",
"emails": [
{
"value": "John4_29_4@cs-sso-us-prod.com",
"type": "work",
"notifications": false,
"verified": false
}
],
"userName": "John4_26_1@cs-sso-us-prod.com",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"employeeNumber": "John4_29_4@cs-sso-us-prod.com",
"companyId": "aa076ada-xxxx-xxxx-xxxx-9300b1c3171d"
}
}
provisionId: "2b41c0c1-15f7-41cc-99bb-a82b5da128a2" is the provisioning request ID. This is a unique number that is used for querying status on the request.id: "ef0bffaf-863f-4b3e-9c4c-bd9c9a8b2ea7" is the SAP Concur user UUID. This is a unique number that is used for this particular user.statusUrl: The location to receive status on the provisioning request
Update the Profile Data of a User
Allows the modification of a single resource.
Scopes
user.provision.write- Refer to Scope Usage for full details.identity.user.coreenterprise.writeonly- Refer to Scope Usage for full details.identity.user.externalID.writeonly- Refer to Scope Usage for full details.spend.user.general.writeonly- Refer to Scope Usage for full details.
Request
PATCH https://www.us.api.concursolutions.com/provisioning/v4/Users/<Concur UUID>
URI
Template
PATCH /provisioning/v4/Users/
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
UUID |
The SAP Concur platform UUID of the user to be updated. |
Headers
Payload
Response
Status Codes
- 200 OK
- 201 Created
- 202 Accepted
- 400 Bad Request
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found
- 408 Request Timeout
- 413 Payload Too Large
- 429 Too Many Requests
- 500 Internal Server Error
- 501 Not Implemented
- 502 Bad Gateway
- 503 Service Unavailable
- 504 Gateway Timeout
Payload
None
Example
Request
PATCH https://www.us.api.concursolutions.com/provisioning/v4/Users/ef0bffaf-863f-4b3e-9c4c-bd9c9a8b2ea7
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"op": "add",
"path": "entitlements",
"value": [
"Expense",
"Invoice",
"Locate",
"Request",
"Travel"
]
},
{
"op": "replace",
"path": "userName",
"value": "John10_9_1_Replacement@sap.com"
}
]
}
Response
200 OK
Content-Type: application/json
{
"addresses": null,
"meta": {
"resourceType": "User",
"created": "2021-04-26T20:07:55.000097Z",
"lastModified": "2021-04-26T20:18:33.000701Z",
"version": 3,
"location": "https://us.api.concursolutions.com/profile/identity/v4/Users/ef0bffaf-863f-4b3e-9c4c-bd9c9a8b2ea7",
"statusUrl": "https://us.api.concursolutions.com/provisioning/v4/provisions/e820c001-c358-4a3e-964a-321dc2a76203/status",
"provisionId": "e820c001-c358-4a3e-964a-321dc2a76203"
},
"displayName": "John",
"name": {
"legalName": "Mr. John Doe",
"honorificSuffix": "VI",
"middleInitial": "J",
"formatted": "Doe, John Joe",
"familyName": "Doe",
"givenName": "John",
"honorificPrefix": "Prof Dr Mr",
"middleName": "Joe"
},
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
"urn:ietf:params:scim:schemas:extension:sap:2.0:User"
],
"active": true,
"id": "ef0bffaf-863f-4b3e-9c4c-bd9c9a8b2ea7",
"emails": [
{
"verified": false,
"type": "work",
"value": "John4_26_1@cs-sso-us-prod.com",
"notifications": false
}
],
"userName": "John_Updated_76@cs-sso-us-prod.com",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"companyId": "aa076ada-80a9-4f57-8e98-9300b1c3171d",
"employeeNumber": "John_Updated_56@cs-sso-us-prod.com"
}
}
provisionId: "e820c001-c358-4a3e-964a-321dc2a76203" is the provisioning request ID. This is a unique number that is used for querying status on the request.id: "ef0bffaf-863f-4b3e-9c4c-bd9c9a8b2ea7" is the SAP Concur user UUID. This is a unique number that is used for this particular user.statusUrl: The location to receive status on the provisioning request
Replace a User Resource
Allows the replacement of an existing resource. In the case where all attributes are not provisioned, system default values will be provisioned.
Scopes
user.provision.write- Refer to Scope Usage for full details.identity.user.coreenterprise.writeonly- Refer to Scope Usage for full details.identity.user.externalID.writeonly- Refer to Scope Usage for full details.-
spend.user.general.writeonly- Refer to Scope Usage for full details.
Request
PUT https://www.us.api.concursolutions.com/provisioning/v4/Users/<Concur UUID>
URI
Template
PUT /provisioning/v4/Users/
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
UUID |
The SAP Concur platform UUID of the user to be updated. |
Headers
Payload
Request
Status Codes
- 200 OK
- 201 Created
- 202 Accepted
- 400 Bad Request
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found
- 408 Request Timeout
- 413 Payload Too Large
- 429 Too Many Requests
- 500 Internal Server Error
- 501 Not Implemented
- 502 Bad Gateway
- 503 Service Unavailable
- 504 Gateway Timeout
Payload
None
Example
Request
PUT https://www.us.api.concursolutions.com/provisioning/v4/Users/ef0bffaf-863f-4b3e-9c4c-bd9c9a8b2ea7
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"userName": "John10_14_1_Replacement@sap.com",
"id": "8f545a90-305f-441b-91cd-a69ad5f548f5",
"active": false,
"name": {
"formatted": "Mr. John Doe1",
"legalName": "Mr. John Doe1",
"middleName": "Joe1",
"middleInitial": "J",
"familyName": "Doe1",
"givenName": "John1",
"hasNoMiddleName": true
},
"emails": [
{
"value": "John10_14_1_Replacement@sap.com",
"type": "work"
}
],
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"employeeNumber": "John10_8_1",
"companyId": "aa076ada-xxxx-xxxx-xxxx-9300b1c3171d"
}
}
Response
200 OK
Content-Type: application/json
{
"meta": {
"resourceType": "User",
"created": "2021-04-29T17:17:47.000380Z",
"lastModified": "2021-04-29T17:17:47.000380Z",
"version": 0,
"location": "https://us.api.concursolutions.com/profile/identity/v4/Users/61bd5549-d68c-407b-8228-9590ae40eaa0",
"statusUrl": "https://us.api.concursolutions.com/provisioning/v4/provisions/03295e27-c9c2-4579-92d8-8b46ec91eff5/status",
"provisionId": "03295e27-c9c2-4579-92d8-8b46ec91eff5"
},
"displayName": "John",
"name": {
"middleInitial": "J",
"middleName": "Joe",
"formatted": "Doe, John Joe",
"honorificPrefix": "Prof Dr Mr",
"legalName": "Mr. John Doe",
"familyName": "Doe",
"givenName": "John",
"honorificSuffix": "VI"
},
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
"urn:ietf:params:scim:schemas:extension:sap:2.0:User"
],
"active": true,
"id": "61bd5549-d68c-407b-8228-9590ae40eaa0",
"emails": [
{
"value": "John4_29_4@cs-sso-us-prod.com",
"type": "work",
"notifications": false,
"verified": false
}
],
"userName": "John4_29_4@cs-sso-us-prod.com",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"employeeNumber": "John4_29_4@cs-sso-us-prod.com",
"companyId": "aa076ada-80a9-4f57-8e98-9300b1c3171d"
}
}
Retrieve User Profile Data
To retrieve profile data for a specific user, the SAP Concur platform has enabled separate endpoints. For additional information for provisioning the specific profiles, please see the documentation for Identity, Spend, and Travel.
Scopes
identity.user.ids.read- Refer to Scope Usage for full details.identity.user.core.read- Refer to Scope Usage for full details.identity.user.coresensitive.read- Refer to Scope Usage for full details.identity.user.enterprise.read- Refer to Scope Usage for full details.travel.user.general.read- Refer to Scope Usage for full details.travel.user.private.read- Refer to Scope Usage for full details.spend.user.general.read- Refer to Scope Usage for full details.
Request
GET https://us.api.concursolutions.com/profile/identity/v4/Users
Request Example
GET https://us.api.concursolutions.com/profile/identity/v4/Users/8f545a90-305f-441b-91cd-a69ad5f548f5
GET https://us.api.concursolutions.com/profile/spend/v4/Users/8f545a90-305f-441b-91cd-a69ad5f548f5
GET https://us.api.concursolutions.com/profile/travel/v4/Users/8f545a90-305f-441b-91cd-a69ad5f548f5
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
ID |
string |
- |
Requested user’s UUID |
Headers
Payload
None
Response
Status Codes
- 200 OK
- 202 Accepted
- 400 Bad Request
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found
- 408 Request Timeout
- 429 Too Many Requests
- 500 Internal Server Error
- 501 Not Implemented
- 502 Bad Gateway
- 503 Service Unavailable
- 504 Gateway Timeout
Payload
- User
- Enterprise User
- Travel User
- Spend User
- Spend Role
- Spend Delegate
- Spend Approver
- Expense User Preference Extension
- Workflow Preference Extension
Example
Request
GET https://us.api.concursolutions.com//profile/identity/v4/Users/ef0bffaf-863f-4b3e-9c4c-bd9c9a8b2ea7
Response
200 OK
Content-Type: application/json
Identity
{
"localeOverrides": {
"preferenceEndDayViewHour": 20,
"preferenceFirstDayOfWeek": "Sunday",
"preferenceDateFormat": "mm/dd/yyyy",
"preferenceCurrencySymbolLocation": "BeforeAmount",
"preferenceHourMinuteSeparator": ":",
"preferenceDefaultCalView": "month",
"preference24Hour": "H:mm",
"preferenceNumberFormat": "1,000.00",
"preferenceStartDayViewHour": 8,
"preferenceNegativeCurrencyFormat": "-100"
},
"addresses": [
{
"country": "US",
"streetAddress": "911 Universal City Plaza",
"postalCode": "91608",
"locality": "Hollywood",
"type": "home",
"region": "CA"
}
],
"timezone": "America/New_York",
"meta": {
"resourceType": "User",
"created": "2020-09-22T14:26:29.000516Z",
"lastModified": "2021-02-10T23:14:18.000733Z",
"version": 16,
"location": "https://us.api.concursolutions.com/profile/identity/v4/Users/8f545a90-305f-441b-91cd-a69ad5f548f5"
},
"displayName": "John",
"name": {
"middleInitial": "J",
"middleName": "Joe",
"formatted": "Doe, John Joe",
"honorificPrefix": "Prof Dr Mr",
"legalName": "Mr. John Doe",
"familyName": "Doe",
"givenName": "John",
"honorificSuffix": "VI",
"hasNoMiddleName": false
},
"phoneNumbers": [
{
"type": "home",
"value": "tel:555-555-5555",
"operatingSystem": null,
"notifications": false,
"primary": false
}
...
],
"emergencyContacts": [
{
"country": "US",
"streetAddress": "911 Universal City Plaza Hollywood, CA 91608 US",
"postalCode": "91608",
"name": "Emergency Contact",
"locality": null,
"phones": [
"555-555-5555"
],
"region": "CA",
"relationship": "Other"
}
],
"preferredLanguage": "en-US",
"title": "Software Engineer",
"dateOfBirth": null,
"nickName": "Francis",
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
"urn:ietf:params:scim:schemas:extension:sap:2.0:User"
],
"externalId": "1234abcd56789e4370",
"active": true,
"id": "8f545a90-305f-441b-91cd-a69ad5f548f5",
"gender": null,
"emails": [
{
"verified": false,
"type": "work",
"value": "john.doe194@BravoPro7.com",
"notifications": true
}
...
{
"verified": false,
"type": "other2",
"value": "john.doe1883@BravoPro7.com",
"notifications": false
}
],
"userName": "john.doe_replacement@BravoPro7.com",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"employeeNumber": "13749670",
"companyId": "aa076ada-80a9-xxxx-xxxx-9300b1c3171d",
"department": "Engineering",
"division": "Theme Park",
"startDate": "2020-09-22T14:26:00.000",
"costCenter": null,
"manager": null,
"terminationDate": null,
"orgUnit": null,
"jobTitle": "Software Engineer"
}
}
Travel
{
"id": "8f545a90-305f-441b-91cd-a69ad5f548f5",
"urn:ietf:params:scim:schemas:extension:travel:2.0:User": {
"ruleClass": {
"name": "Default Travel Class",
"id": 560485
},
"travelCrsName": null,
"xmlProfileSyncId": "",
"travelNameRemark": "",
"orgUnit": null,
"customFields": [
{
"name": "Canary ID"
}
...
{
"name": "trainline trip purpose 1"
}
],
"manager": null,
"groups": []
}
Spend
{
"schemas": [
"urn:com.concur.spend.user.model.scim.ScimResource",
"urn:ietf:params:scim:schemas:extension:spend:2.0:Role",
"urn:ietf:params:scim:schemas:extension:spend:2.0:WorkflowPreference",
"urn:ietf:params:scim:schemas:extension:spend:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:Payroll",
"urn:ietf:params:scim:schemas:extension:spend:2.0:UserPreference",
"urn:ietf:params:scim:schemas:extension:spend:2.0:Delegate",
"urn:ietf:params:scim:schemas:extension:spend:2.0:Approver"
],
"id": "8f545a90-305f-441b-91cd-a69ad5f548f5",
"externalId": null,
"meta": null,
"urn:ietf:params:scim:schemas:extension:spend:2.0:Role": {
"roles": [
{
"roleName": "REPORTING_CONFIG_ADMIN"
}
...
{
"roleName": "EXP_USER"
}
]
},
"urn:ietf:params:scim:schemas:extension:spend:2.0:WorkflowPreference": {
"emailStatusChangeOnCashAdvance": true,
"emailAwaitApprovalOnCashAdvance": true,
"emailStatusChangeOnReport": true,
"emailAwaitApprovalOnReport": true,
"promptForApproverOnReportSubmit": true,
"emailStatusChangeOnTravelRequest": true,
"emailAwaitApprovalOnTravelRequest": true,
"promptForApproverOnTravelRequestSubmit": true,
"emailStatusChangeOnPayment": true,
"emailAwaitApprovalOnPayment": true,
"promptForApproverOnPaymentSubmit": true
},
"urn:ietf:params:scim:schemas:extension:spend:2.0:User": {
"reimbursementCurrency": "USD",
"reimbursementType": "ADP_PAYROLL",
"ledgerCode": "DEFAULT",
"country": "US",
"stateProvince": "WA",
"locale": "en-US",
"testEmployee": false,
"nonEmployee": false,
"customData": [
{
"id": "custom20",
"value": "testing"
}
...
{
"id": "custom18",
"value": "testing"
}
]
},
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:Payroll": {
"adp": {
"companyCode": "string",
"deductionCode": "string",
"employeeFileNumber": "string"
}
},
"urn:ietf:params:scim:schemas:extension:spend:2.0:UserPreference": {
"showImagingIntro": true,
"expenseAuditRequired": "ALWAYS",
"allowCreditCardTransArrivalEmails": true,
"allowReceiptImageAvailEmails": true,
"promptForCardTransactionsOnReport": true,
"autoAddTripCardTransOnReport": true,
"promptForReportPrintFormat": true,
"defaultReportPrintFormat": "DETAILED",
"showTotalOnReport": true,
"showExpenseOnReport": "PARENT",
"showInstructHelpPanel": true,
"useQuickItinAsDefault": false
},
"urn:ietf:params:scim:schemas:extension:spend:2.0:Delegate": {},
"urn:ietf:params:scim:schemas:extension:spend:2.0:Approver": {
"report": [
{
"approver": {
"value": "7a183cbe-1f4a-44f4-891c-8eff3608975e"
},
"primary": true
}
]
...
"budget": [
{
"approver": {
"value": "7a183cbe-1f4a-44f4-891c-8eff3608975e"
},
"primary": true
}
]
}
}
Retrieve a Summary Provisioning Request Status
Retrieves a summary provisioning request status.
Scopes
user.provision.read- Refer to Scope Usage for full details.
Request
URI
Template
GET /provisioning/v4/provisions/{provision-id}/status
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
provision-id |
string |
- |
The provisioning request UUID |
Headers
Content-Typeis used to specify the nature of the data in the body of an entity, by giving type and subtype identifiers, and by providing auxiliary information that may be required for certain types (https://www.w3.org/Protocols/rfc1341/4_Content-Type.html)application/json,application/scim+json
Payload
None
Response
Status Codes
- 200 OK
- 400 Bad Request
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found
- 408 Request Timeout
- 429 Too Many Requests
- 500 Internal Server Error
- 501 Not Implemented
- 502 Bad Gateway
- 503 Service Unavailable
- 504 Gateway Timeout
Payload
Example
Request
GET https://www.us.api.concursolutions.com/provisioning/v4/provisions/0e00f6a4-6798-4f66-9f47-1e944b619b2e/status
Response
200 OK
Content-Type: application/json
{
"schemas": [
"urn:ietf:params:scim:schemas:extension:concur:2.0:Provision:Status"
],
"id": "14b15c4b-59a1-42fb-bdb5-999bb3d38d5d",
"operationsCount": {
"total": 1,
"success": 1,
"failed": 0,
"pending": 0
},
"status": {
"completed": true,
"success": true
},
"meta": {
"location": "https://www.us.api.concursolutions.com/provisioning/v4/provisions/0e00f6a4-6798-4f66-9f47-1e944b619b2e/status",
"created": "2020-07-15T23:03:07.859+0000",
"lastModified": "2020-07-15T23:03:07.859+0000",
"resourceType": "ProvisionRequest",
"correlationId": "d5192a1d-3385-4afc-9e8d-4aeff8b58a48"
}
}
Retrieve a Detailed Provisioning Request Status
Retrieves a detailed provisioning request status.
Scopes
user.provision.read- Refer to Scope Usage for full details.
Request
GET https://www.us.api.concursolutions.com/provisioning/v4/provisions/{provision-id}/status?attributes=operations
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
attributes |
string |
operations |
Response includes operations when specified. |
startIndex |
Integer |
Non-negative Integer |
The 1-based index of the first result in the current set of list results. |
count |
Integer |
Non-negative Integer |
Specifies the desired operations per page. |
state |
string |
status |
Can filter results based on:[pending, success, failed] |
Headers
Payload
None
Response
Status Codes
- 200 OK
- 400 Bad Request
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found
- 408 Request Timeout
- 429 Too Many Requests
- 500 Internal Server Error
- 501 Not Implemented
- 502 Bad Gateway
- 503 Service Unavailable
- 504 Gateway Timeout
Payload
Example
Request
GET https://www.us.api.concursolutions.com/provisioning/v4/provisions/0e00f6a4-6798-4f66-9f47-1e944b619b2e/status?attributes=operations
Response
200 OK
Content-Type: application/json
{
"itemsPerPage": 1,
"meta": {
"location": "https://us.api.concursolutions.com/provisioning/v4/provisions/0e00f6a4-6798-4f66-9f47-1e944b619b2e/status",
"created": "2021-04-22T15:03:25.975+0000",
"lastModified": "2021-04-22T15:03:27.558+0000",
"provisionType": "User",
"resourceType": "ProvisionRequest",
"correlationId": "5d15903c-1921-49f1-8d29-329525bb4a4f",
"completed": "2021-04-22T15:03:27.558+0000"
},
"operationsCount": {
"total": 1,
"success": 1,
"failed": 0,
"pending": 0
},
"totalResults": 1,
"schemas": [
"urn:ietf:params:scim:schemas:extension:concur:2.0:Provision:Status"
],
"status": {
"completed": true,
"success": true
},
"id": "ef0bffaf-863f-4b3e-9c4c-bd9c9a8b2ea7",
"operations": [
{
"id": "1",
"status": {
"completed": true,
"success": true
},
"resource": {
"id": "46702256-0123-4e83-83ff-d1a55adfc607",
"type": "User"
},
"bulkId": "gen-temp-bulk-id",
"extensions": [
{
"name": "urn:ietf:params:scim:schemas:extension:spend:2.0:WorkflowPreference",
"status": {
"completed": true,
"success": true,
"code": "200",
"result": "no-op"
}
},
{
"name": "urn:ietf:params:scim:schemas:extension:spend:2.0:Role",
"status": {
"completed": true,
"success": true,
"code": "200",
"result": "no-op"
}
},
{
"name": "urn:ietf:params:scim:schemas:extension:spend:2.0:UserPreference",
"status": {
"completed": true,
"success": true,
"code": "200",
"result": "no-op"
}
},
{
"name": "urn:ietf:params:scim:schemas:extension:spend:2.0:Approver",
"status": {
"completed": true,
"success": true,
"code": "200",
"result": "no-op"
}
},
{
"name": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:Payroll",
"status": {
"completed": true,
"success": true,
"code": "200",
"result": "no-op"
}
},
{
"name": "urn:ietf:params:scim:schemas:core:2.0:User",
"status": {
"completed": true,
"success": true,
"code": "200",
"result": "success"
}
},
{
"name": "urn:ietf:params:scim:schemas:extension:spend:2.0:User",
"status": {
"completed": true,
"success": true,
"code": "200",
"result": "no-op"
}
},
{
"name": "urn:ietf:params:scim:schemas:extension:spend:2.0:Delegate",
"status": {
"completed": true,
"success": true,
"code": "200",
"result": "no-op"
}
},
{
"name": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
"status": {
"completed": true,
"success": true,
"result": "success"
}
},
{
"name": "urn:ietf:params:scim:schemas:extension:travel:2.0:User",
"status": {
"completed": true,
"success": true,
"code": "200",
"result": "no-op"
}
}
]
}
],
"startIndex": 1
}
Retrieve Supported Resource Types
Retrieves supported resource types.
Scopes
user.provision.read- Refer to Scope Usage for full details.
Request
URI
Template
GET /provisioning/v4/ResourceTypes
Parameters
None
Headers
Payload
-
Response
Status Codes
- 200 OK
- 400 Bad Request
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found
- 408 Request Timeout
- 429 Too Many Requests
- 500 Internal Server Error
- 501 Not Implemented
- 502 Bad Gateway
- 503 Service Unavailable
- 504 Gateway Timeout
Payload
None
Example
Request
GET https://www.us.api.concursolutions.com/provisioning/v4/ResourceTypes
Response
200 OK
Content-Type: application/json
[
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:ResourceType"
],
"id": "User",
"name": "User",
"endpoint": "/Users",
"description": "Concur User",
"schema": "urn:ietf:params:scim:schemas:core:2.0:User",
"schemaExtensions": [
{
"schema": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
"required": true
},
{
"schema": "urn:ietf:params:scim:schemas:extension:travel:2.0:User",
"required": false
},
{
"schema": "urn:ietf:params:scim:schemas:extension:spend:2.0:User",
"required": false
},
{
"schema": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:Payroll",
"required": false
},
{
"schema": "urn:ietf:params:scim:schemas:extension:spend:2.0:Approver",
"required": false
},
{
"schema": "urn:ietf:params:scim:schemas:extension:spend:2.0:Delegate",
"required": false
},
{
"schema": "urn:ietf:params:scim:schemas:extension:spend:2.0:Role",
"required": false
},
{
"schema": "urn:ietf:params:scim:schemas:extension:spend:2.0:WorkflowPreference",
"required": false
},
{
"schema": "urn:ietf:params:scim:schemas:extension:spend:2.0:UserPreference",
"required": false
}
],
"meta": {
"location": "https://us.api.concursolutions.com.com/provisioning/v4/ResourceTypes/User",
"resourceType": "ResourceType"
}
}
]
Retrieve Supported Schemas
Retrieves supported schemas.
Scopes
user.provision.read- Refer to Scope Usage for full details.
Request
URI
Template
GET /provisioning/v4/Schemas
Parameters
None
Headers
Payload
None
Response
Status Codes
- 200 OK
- 400 Bad Request
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found
- 408 Request Timeout
- 429 Too Many Requests
- 500 Internal Server Error
- 501 Not Implemented
- 502 Bad Gateway
- 503 Service Unavailable
- 504 Gateway Timeout
Payload
None
Example
Request
GET https://www.us.api.concursolutions.com/provisioning/v4/Schemas
Response
200 OK
Content-Type: application/json
[
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"Resources": [
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Schema"
],
"id": "urn:ietf:params:scim:api:messages:concur:2.0:Error",
"name": "Concur Error",
"type": "complex",
"description": "Concur Error",
"attributes": [
{
"name": "messages",
"type": "complex",
"multiValue": true,
"description": "Additional messages in case of errors / warnings",
"mutabbility": "readOnly",
"required": false,
"subAttributes": [
{
"name": "code",
"type": "string",
"description": "Message Code",
"mutabbility": "readOnly",
"required": true
},
{
"name": "message",
"type": "string",
"description": "Message description",
"mutabbility": "readOnly",
"required": false
},
{
"name": "schemaPath",
"type": "string",
"description": "Relative schema path of attribute",
"mutabbility": "readOnly",
"required": false
},
{
"name": "type",
"type": "string",
"description": "Message Type",
"mutabbility": "readOnly",
"required": true,
"canonicalValues": [
"error",
"warning"
]
}
]
}
],
"meta": {
"resourceType": "schemas"
}
},
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Schema"
],
"id": "urn:ietf:params:scim:schemas:extension:concur:2.0:Provision:Status",
"name": "Provision Status",
"type": "complex",
"description": "Provision Status",
"attributes": [
{
"mutability": "readOnly",
"description": "Unique identifier (uuid) for the provisioning request",
"returned": "always",
"name": "id",
"multiValued": false,
"type": "string",
"uniqueness": "global",
"caseExact": false,
"required": true
},
{
"mutability": "readOnly",
"description": "Status of the provision request",
"returned": "always",
"subAttributes": [
{
"name": "completed",
"type": "boolean",
"description": "Is provisioning completed?",
"mutability": "readOnly",
"required": true
},
{
"name": "success",
"type": "boolean",
"description": "Is provisioning successful?",
"mutabbility": "readOnly",
"required": false
}
],
"name": "status",
"multiValued": false,
"type": "complex",
"caseExact": true,
"required": true
},
Schema
User
| Name | Type | Format | Description |
|---|---|---|---|
active |
boolean |
true/false |
Required if true, the user is active. |
addresses |
object |
- | A physical mailing address for this user. Supported values: work, home, other |
country |
string |
- | A two-letter country code defined in ISO 3166-1 alpha-2. |
locality |
string |
- | The city or locality. |
postalCode |
string |
- | The zip code or postal code. |
region |
string |
- | The state or region. |
streetAddress |
string |
- | The full street address component, which may include house number, street name, P.O. box, and multi-line extended street address information. |
type |
string |
- | A label indicating the function of the address. Examples: work, home |
dateOfBirth |
string |
YYY-MM-DD |
The user's date of birth. |
displayName |
string |
- | The name of the user, suitable for display. This name should be the full name of the user. |
emails |
object |
- | Required Email addresses for the user. The value should be canonicalized by the service provider. |
dateAdded |
string |
- | The date and time the email was added to the user's profile. |
dateVerified |
string |
- | The date and time the email was verified. |
notifications |
boolean |
true/false |
If true, user has opted in for notification emails. |
type |
string |
- | A label indicating the attribute's function. Example: Work, home |
value |
string |
- | Required Email address value. |
verified |
boolean |
true/false |
If true, an email has been verified by the user. |
emergencyContacts |
object |
- | Emergency Contact information for the user. |
country |
string |
- | A two-letter country code defined in ISO 3166-1 alpha-2 of the emergency contact. |
emails |
string |
- | Emails of the emergency contact. |
locality |
string |
- | The city or locality of the emergency contact. |
name |
string |
- | Name of the emergency contact. |
phones |
string |
- | Phone numbers of the emergency contact. |
postalCode |
string |
- | The zip code or postal code of the emergency contact. |
region |
string |
- | The state or region of the emergency contact. |
relationship |
string |
- | Required Emergency contact relationship. Supported values: Spouse, Brother, Sister, Parent, Life Partner, Other |
streetAddress |
string |
- | The full street address component of the emergency contact, which may include house number, street name, P.O. box, and multi-line extended street address information. |
entitlements |
string |
- | The features enabled for the user. |
externalId |
string |
- | User identifier from the provisioning user. |
gender |
string |
- | The user's gender. Supported values: Male, Female, Others |
id |
string |
UUID |
Required Unique identifier for the user. |
localeOverrides |
object |
- | Support for users who want to override locale settings. |
preference24Hour |
string |
- | Preferred 24 hour format for the user. Supported values: h:mm AM/PM, H:mm |
preferenceCurrencySymbolLocation |
string |
- | Preferred currency symbol location for the user. Supported values: BeforeAmount, AfterAmount |
preferenceDateFormat |
string |
- | Preferred date format for the user. Supported values: mm/dd/yyyy, mm.dd.yyyy, mm-dd-yyyy, dd/mm/yyyy, dd.mm.yyyy, dd-mm-yyyy, yyyy/mm/dd, yyyy.mm.dd, yyyy-mm-dd |
preferenceDefaultCalView |
string |
- | Preferred default calendar view for the user. Supported values: day, week, month |
preferenceDistance |
string |
- | Preferred distance metric. Supported values: mile, km |
preferenceEndDayViewHour |
integer |
- | Preferred hour setting for the end of day. Supported values: 0-23 |
preferenceFirstDayOfWeek |
string |
- | Preferred first day of the week for the user. |
preferenceHourMinuteSeparator |
string |
- | Preferred separator between hour and minute. Supported values: :, . |
preferenceNegativeCurrencyFormat |
string |
- | Preferred negative currency format for the user. Supported values: -100, (100) |
preferenceNegativeNumberFormat |
string |
- | Preferred negative number format for the user. Supported values: -100, (100) |
preferenceNumberFormat |
string |
- | Preferred number format for the user. Supported values: 1,000.00, 1.000,00, 1 000,00, 1'000.00, 1'000,00 |
preferenceStartDayViewHour |
integer |
- | Preferred start of day for the user. Begins at 1. |
meta |
object |
- | - |
name |
object |
- | Required The user's name. |
familyName |
string |
- | Required The family or last name of the user. |
formatted |
string |
- | The full name, including all middle names, title, and suffixes as appropriate, formatted for display Example: Ms. Barbara J Jensen, III |
givenName |
string |
- | Required The given or first name of the user. |
hasNoMiddleName |
boolean |
true/false |
If true, the user does not have a middle name. |
honorificPrefix |
string |
- | The honorific or title prefix(es) of the user. |
honorificSuffix |
string |
- | The honorific suffix(es) of the user. |
legalName |
string |
- | The legal name of the user. |
middleInitial |
string |
- | The middle initial of the user's middle name, if the user has a middle name. |
middleName |
string |
- | The middle name(s) of the user. |
nickName |
string |
- | The casual way to address the user. |
phoneNumbers |
object |
- | Phone numbers for the user. |
countryCode |
string |
- | A two-letter code defined in ISO 3166-1 alpha-2 denoting the country the phone number was issued in. |
display |
string |
- | A phone number for display. |
notifications |
boolean |
true/false |
If true, the user has opted in for mobile device notifications. |
operatingSystem |
string |
- | The operating system of the device, when the phone is cellphone. Supported values: Android Phone, Android Tablet, Blackberry, iOS Phone, iOS Tablet, Not a smartphone, Other iOS device, Other smartphone, Unknown, Window Mobile |
primary |
boolean |
true/false |
If true, this is the primary device for mobile devices. |
type |
string |
- | A label indicating the phones's function. Example: Work, Home |
value |
string |
- | Phone number value. |
preferredLanguage |
string |
- | Indicates the user's preferred written or spoken language. Used for selecting a localized user interface. |
timezone |
string |
olson |
The user's time zone. Example: America/Los_Angeles |
Payroll |
PayrollExtension |
- | - |
User |
EnterpriseUser |
- | - |
Approver |
SpendApprover |
- | - |
Delegate |
SpendDelegate |
- | - |
Role |
SpendRole |
- | - |
User |
SpendUser |
- | - |
UserPreference |
ExpenseUserPreferenceExtension |
- | - |
WorkflowPreference |
WorkflowPreferenceExtension |
- | - |
User |
TravelUser |
- | - |
userName |
string |
- | Required The name that can be used to log in to CTE. |
Travel User
| Name | Type | Format | Description |
|---|---|---|---|
ruleClass |
complex |
- | Required Defines the rule class for the travel user either ID or name should be provided. |
travelNameRemark |
string |
- | Travel name remark. |
xmlProfileSyncId |
string |
- | User-assigned Travel user identifier that allows the user profile to be synchronized with other vendors. |
travelCrsName |
string |
- | The name of the profile in the GDS system. |
groups |
integer |
- | List of user groups that user belongs to for certain permissions. |
manager |
complex |
- | Travel approver of this user. |
customFields |
complex |
- | User can set values to custom data fields. |
Workflow Preference Extension
| Name | Type | Format | Description |
|---|---|---|---|
emailAwaitApprovalOnCashAdvance |
boolean |
true/false |
If true, an email is sent when a cash advance is awaiting approval. Default: true |
emailAwaitApprovalOnPayment |
boolean |
true/false |
If true, an email is sent when a payment is awaiting approval. Default: true |
emailAwaitApprovalOnReport |
boolean |
true/false |
If true, an email is sent when a report is awaiting approval. Default: true |
emailAwaitApprovalOnTravelRequest |
boolean |
true/false |
If true, an email is sent when a travel request is awaiting approval. Default: true |
emailStatusChangeOnCashAdvance |
boolean |
true/false |
If true, an email is sent when the cash advance status changes. Default: true |
emailStatusChangeOnPayment |
boolean |
true/false |
If true, an email is sent when the payment status changes. Default: true |
emailStatusChangeOnReport |
boolean |
true/false |
If true, an email is sent when the report status changes. Default: true |
emailStatusChangeOnTravelRequest |
boolean |
true/false |
If true, an email is sent when the travel request status changes. Default: true |
promptForApproverOnPaymentSubmit |
boolean |
true/false |
If true, a prompt for approver is displayed when submitting a payment. Default: false |
promptForApproverOnReportSubmit |
boolean |
true/false |
If true, a prompt for approver is displayed when submitting a report. Default: false |
promptForApproverOnTravelRequestSubmit |
boolean |
true/false |
If true, a prompt for approver is displayed when submitting a travel request. Default: false |
Bulk Request
| Name | Type | Format | Description |
|---|---|---|---|
schemas |
string |
- | - |
Operations |
object |
- | - |
data |
User | - | - |
method |
string |
- | Supported values: POST, PUT, PATCH |
path |
string |
- | - |
Spend User
| Name | Type | Format | Description |
|---|---|---|---|
budgetCountryCode |
string |
Valid ISO 3166 country code for Budget. | |
country |
string |
- | Required Valid ISO 3166 country code. |
ledgerCode |
string |
- | Ledger code to associate with the user. |
locale |
string |
- | Required Valid locale from the list of configured locales as defined in [RFC5646]. Example: en-US |
reimbursementCurrency |
string |
- | Required Valid three digit currency code in the list of system reimbursement currencies. |
reimbursementType |
object |
- | Required The reimbursement type for the user. |
stateProvince |
string |
- | Valid ISO sub country code. Example: WA |
Spend Role
| Name | Type | Format | Description |
|---|---|---|---|
roles |
object |
- | Expense roles for the employee. |
roleGroups |
object |
- | Group(s) to be associated with the Expense role. |
roleName |
object |
- | Required Expense role for the employee. |
Spend Delegate
| Name | Type | Format | Description |
|---|---|---|---|
delegateProdCode |
object |
- | A list of delegates associated with the delegate's product code. |
canApprove |
boolean |
true/false |
If true, the delegate can approve. |
canPrepare |
boolean |
true/false |
If true, the delegate can prepare. |
canPrepareForApproval |
boolean |
true/false |
If true, the delegate can prepare for approval. |
canReceiveApprovalEmail |
boolean |
true/false |
If true, the delegate can receive approval emails. |
canReceiveEmail |
boolean |
true/false |
If true, the delegate can receive emails. |
canSubmit |
boolean |
true/false |
If true, the delegate can submit. |
canSubmitTravelRequest |
boolean | true/false |
If true, the delegate can submit travel request. |
canUseBi |
boolean | true/false |
If true, the delegate can use BI. |
canViewReceipt |
boolean |
true/false |
If true, the delegate can view receipts. |
delegate |
object |
- | Required User reference for the delegate. |
$ref |
string |
- | The URI reference for the user. |
displayName |
string |
- | The username for the user. |
employeeNumber |
string |
- | Required The employee number for the user. |
value |
object |
- | The internal UUID identifier for the user. |
temporaryDelegatation |
object |
- | Determines if delegate can temporarily approve. |
temporaryDelegationFromDate |
string |
- | Start date for delegate's temporary approval permissions. |
temporaryDelegationToDate |
string |
- | End date for delegate's temporary approval permissions. |
Spend Approver
| Name | Type | Format | Description |
|---|---|---|---|
approverType |
object |
- | A list of approvers associated with the approver's type. |
approver |
object |
- | The user reference for the approver. |
$ref |
string |
- | The URI reference for the user. |
displayName |
string |
- | The username for the user. |
employeeNumber |
string |
- | Required The employee number for the user. |
value |
object |
- | The internal UUID identifier for the user. |
primary |
boolean |
true/false |
Required If true, the associated user is the primary approver. |
Enterprise User
| Name | Type | Format | Description |
|---|---|---|---|
companyId |
string |
- | Required The SAP Concur ID of the company. |
costCenter |
string |
- | Employee cost center for product. |
department |
string |
- | User supplied department name. |
division |
string |
- | User supplied division name. |
employeeNumber |
string |
- | User supplied employee's number within the company, unique for the company. |
jobTitle |
string |
- | User's job title in the company. |
manager |
object |
- | The manager of the user. |
$ref |
string |
- | The URI of the SCIM resource representing the referenced user. |
displayName |
string |
- | The referenced user's display name. |
employeeNumber |
string |
- | The referenced user's employee number, if it is an Enterprise user. |
value |
string |
- | The referenced user's UUID. |
orgUnit |
string |
- | User supplied org unit name. |
organization |
string |
- | Company name. |
self |
object |
- | A reference to the user. |
$ref |
string |
- | The URI of the SCIM resource representing the referenced user. |
startDate |
string |
YYYY-MM-DD |
Start date. |
terminationDate |
string |
YYYY-MM-DD |
Termination date. If the employee is terminated, this can also be used to calculate the data retention period. |
Expense User Preference Extension
| Name | Type | Format | Description |
|---|---|---|---|
allowCreditCardTransArrivalEmails |
boolean |
true/false |
If true, allows credit card transaction arrival notification emails. Default: true |
allowReceiptImageAvailEmails |
boolean |
true/false |
If true, sends an email when faxed receipts are successfully received. Default: true |
autoAddTripCardTransOnReport |
boolean |
true/false |
If true, adds company card transactions within trip dates to one (1) click expense report. |
defaultReportPrintFormat |
string |
- | Default expense report print type. Supported values: RECEIPTS. DETAILED, FAX |
expenseAuditRequired |
string |
- | Expense audit is required. Supported values: NEVER, REQUIRED, ALWAYS |
processorReportAccess |
string |
- | Report access for processor roles. Supported values: Expense Processor, Expense Processor Audit, Expense Processor Manager |
promptForCardTransactionsOnReport |
boolean |
true/false |
If true, displays a prompt for company card transactions when creating a new report. Default: true |
promptForReportPrintFormat |
boolean |
true/false |
If true, displays a prompt for the report format before printing. |
showExpenseOnReport |
string |
- | Show expenses on detailed report. |
showImagingIntro |
boolean |
true/false |
If true, displays imaging introduction. Default: true |
showInstructHelpPanel |
boolean |
true/false |
If true, displays instructional help. Default: true |
showTotalOnReport |
boolean |
true/false |
If true, displays report totals on detailed report. Supported values: ALL, PARENT, NOTHING |
useQuickItinAsDefault |
boolean |
true/false |
If true, uses quick itinerary as default. |
Payroll Extension
| Name | Type | Format | Description |
|---|---|---|---|
adp |
object |
- | ADP settings for employee. |
companyCode |
string |
- | Required The company code for the employee within ADP. |
deductionCode |
string |
- | Required The deduction code for the employee within ADP. |
employeeFileNumber |
string |
- | Required The identifier for the employee within ADP, also known as the Employee File Number. |
Provision Status
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
UUID |
Required Unique identifier for the provisioning request. |
operations |
object |
- | The status of each operation of the provisioning request. |
extensions |
object |
- | The extensions' status. |
messages |
object |
- | Additional messages in case of errors/warnings. |
code |
string |
- | Required Message code. |
message |
string |
- | The message description. |
schemaPath |
string |
- | Relative schema path of attribute. |
type |
string |
- | Required Message type. Supported values: error, warning, user |
name |
string |
- | Required Extension name. |
status |
object |
- | Required Status of the operation. |
code |
string |
- | HTTP status code. |
completed |
boolean |
true/false |
Required If true, the processing extension is complete. |
result |
string |
- | The current processing status. |
success |
boolean |
true/false |
If true, the processing extension was successful. |
id |
string |
- | Required Identifier of the operation. |
resource |
object |
- | Resource details. |
id |
string |
UUID |
Unique identifier of the resource. |
type |
string |
- | Resource type. |
status |
object |
- | Required Status of the operation. |
completed |
boolean |
true/false |
Required If true, the provisioning is complete. |
success |
boolean |
true/false |
If true, the provisioning is successful. |
Error
| Name | Type | Format | Description |
|---|---|---|---|
messages |
object |
- | Additional messages in case of errors/warnings. |
code |
string |
- | Required Message code. |
message |
string |
- | Message description. |
schemaPath |
string |
- | Relative schema path of attribute. |
type |
string |
- | Required Message type. |
Definitions
Name of Release Note
| Information First Published | Information Last Modified | Feature Target Release Date |
|---|---|---|
| March 2021 | - | June 2021 |
| Any changes since the previous monthly release are highlighted in yellow in this release note. |
Overview
The User Provisioning Service allows clients and partners to create, update, replace/delete (CRUD) Concur users using the new "User Provisioning Service. Once a user is provisioned, the user identity is setup in Profile, Travel and Spend.
For more information, please see User Provisioning API documentation
Business Purpose / Client Benefit
The user provisioning service allows clients & partners to provision users faster and with increased access to user data attributes.
Configuration / Feature Activation
The feature is available with web services and configuration is required to use it.
Spend User Provisioning
Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.
Spend User Provisioning allows callers to provision a user in the SAP Concur spend domain. This is an asynchronous downstream process from the User Provisioning v4 service. Currently spend user data can be created, modified, and replaced with the POST, PATCH, and PUT provisioning operations.
Limitations: This API is only available to partners who have been granted access. Access to this documentation does not provide access to the API.
Spend User Provisioning
- Provisioning a Spend User Resources
- Updating existing Spend User Resources
- Replacing existing Spend User Resources
- Schemas
Provisioning a New Spend Resource
Creates one or more provisioning request containing spend relevant data using the /provision/v4/Bulk endpoint. This section discusses the spend extensions and how to use them in tandem with the core extensions to provision a user with spend data. In order to create a user within the SAP Concur interface, the provision request must contain the information required to also provision the core user. The Spend User extension is the required foundation on which the other spend extensions depend. Without a successful Spend User save, the other spend extensions cannot succeed.
POST is used to create a new resource.
Scopes
spend.user.general.writeonly - Refer to Scope Usage for full details.
Request
URI
Template
POST https://www.us.api.concursolutions.com/provisioning/v4/Bulk/
Parameters
None.
Payload
Response
Status Codes
- 200 OK
- 400 Bad Request
- 401 Unauthorized
- 402 Payment Required
- 403 Forbidden
- 500 Internal Server Error
- 502 Bad Gateway
Headers
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7231 Content-Type
Payload
Examples
Request
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:BulkRequest"
],
"failOnErrors": 1,
"Operations": [
{
"method": "POST",
"path": "/Users",
"bulkId": "bulk-operation-1",
"data": {
"userName": "Chris.doe198@sap.com",
"active": true,
"name": {
"formatted": "Chris Doe",
"legalName": "Chris Doe",
"familyName": "Doe",
"givenName": "Chris"
},
"emails": [
{
"value": "Chris.doe198@sap.com",
"type": "Work"
}
],
"entitlements": [
"Expense"
],
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"employeeNumber": "3749",
"companyId": "xxxxxxxx-xxx-xxx-xxx-9300b1c317xxx"
},
"urn:ietf:params:scim:schemas:extension:spend:2.0:User": {
"reimbursementCurrency": "USD",
"reimbursementType": "CONCUR_PAY",
"ledgerCode": "DEFAULT",
"country": "US",
"stateProvince": "WA",
"locale": "en-US",
"customData": [
{
"id": "custom1",
"value": "testing"
},
{
"id": "custom2",
"value": "tested"
},
{
"id": "orgUnit1",
"value": "testDepartment"
},
{
"id": "orgUnit2",
"value": "testSquadAlpha"
}
]
},
"urn:ietf:params:scim:schemas:extension:spend:2.0:Approver": {
"request": [
{
"approver": {
"employeeNumber": "requestApprover"
},
"primary": true
}
],
"report": [
{
"approver": {
"employeeNumber": "reportApprover"
},
"primary": false
}
]
},
"urn:ietf:params:scim:schemas:extension:spend:2.0:Delegate": {
"expense": [
{
"canApprove": true,
"canPrepare": true,
"canPrepareForApproval": true,
"canReceiveApprovalEmail": true,
"canReceiveEmail": true,
"canSubmit": true,
"canSubmitTravelRequest": true,
"canUseBi": true,
"canViewReceipt": true,
"delegate": {
"employeeNumber": "expenseDelegate"
},
"temporaryDelegatation": {
"temporaryDelegationFromDate": "2020-02-19T03:15:00.000Z",
"temporaryDelegationToDate": "2020-02-19T03:59:00.000Z"
}
},
{
"canApprove": true,
"canPrepare": true,
"canPrepareForApproval": true,
"canReceiveApprovalEmail": true,
"canReceiveEmail": true,
"canSubmit": true,
"canSubmitTravelRequest": true,
"canUseBi": true,
"canViewReceipt": true,
"delegate": {
"employeeNumber": "expenseDelegate"
},
"temporaryDelegatation": {
"temporaryDelegationFromDate": "2020-02-19T03:15:00.000Z",
"temporaryDelegationToDate": "2020-02-19T03:59:00.000Z"
}
}
]
},
"urn:ietf:params:scim:schemas:extension:spend:2.0:Role": {
"roles": [
{
"roleName": "EXP_USER",
"roleGroups": ["R&D-Dev-Exp", "R&D-QA-Exp"]
}
]
},
"urn:ietf:params:scim:schemas:extension:spend:2.0:WorkflowPreference": {
"emailStatusChangeOnCashAdvance": true,
"emailAwaitApprovalOnCashAdvance": true,
"emailStatusChangeOnReport": true,
"emailAwaitApprovalOnReport": true,
"promptForApproverOnReportSubmit": true,
"emailStatusChangeOnTravelRequest": true,
"emailAwaitApprovalOnTravelRequest": true,
"promptForApproverOnTravelRequestSubmit": true,
"emailStatusChangeOnPayment": true,
"emailAwaitApprovalOnPayment": true,
"promptForApproverOnPaymentSubmit": true
},
"urn:ietf:params:scim:schemas:extension:spend:2.0:UserPreference": {
"allowCreditCardTransArrivalEmails": true,
"allowReceiptImageAvailEmails": true,
"promptForCardTransactionsOnReport": true,
"autoAddTripCardTransOnReport": true,
"promptForReportPrintFormat": true,
"defaultReportPrintFormat": "DETAILED",
"showTotalOnReport": true,
"showExpenseOnReport": "ALL",
"showInstructHelpPanel": true,
"showImagingIntro": true,
"expenseAuditRequired": "REQUIRED",
"useQuickItinAsDefault": true
},
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:Payroll": {
"adp": {
"companyCode": "companyCode",
"deductionCode": "HLTH",
"employeeFileNumber": "1234"
}
}
}
}
]
}
Updating Existing Spend User Resources
Creates one or more provision requests using the provision/v4/Bulk endpoint to patch existing spend user resources.
PATCH requests modify the resource.
Scopes
spend.user.general.writeonly - Refer to Scope Usage for full details.
Request
URI
Template
POST https://www.us.api.concursolutions.com/provisioning/v4/Bulk/
Parameters
None.
Headers
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN NamespaceContent-Typeis used to specify the nature of the data in the body of an entity, by giving type and subtype identifiers, and by providing auxiliary information that may be required for certain types (https://www.w3.org/Protocols/rfc1341/4_Content-Type.html)application/json,application/scim+json
Payload
Response
Status Codes
- 200 OK
- 400 Bad Request
- 401 Unauthorized
- 402 Payment Required
- 403 Forbidden
- 404 Not Found
- 500 Internal Server Error
- 502 Bad Gateway
- 503 Service Unavailable
Headers
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7231 Content-Type
Payload
Examples
Request
- Note that UUID must be in the path of the request.
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:BulkRequest",
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"failOnErrors": 1,
"Operations": [
{
"method": "PATCH",
"path": "/Users/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"data": {
"Operations": [
{
"op": "replace",
"path": "urn:ietf:params:scim:schemas:extension:spend:2.0:User:country",
"value": "US"
},
{
"op": "add",
"value": {
"urn:ietf:params:scim:schemas:extension:spend:2.0:User": {
"locale": "es-419",
"reimbursementType": "PAY_PAL",
"customData": [
{
"id": "custom1",
"value": "patchChangeCustom1"
},
{
"id": "custom8",
"value": "newCustomObject"
}
]
}
}
},
{
"op": "add",
"value": {
"urn:ietf:params:scim:schemas:extension:spend:2.0:Approver": {
"budget": [
{
"approver": {
"value": "aaaaaaaa-bbbb-cccc-aaaa-bbbbbbbbbbb3",
"displayName": "TestApprover@test.com",
"employeeNumber": "100001",
"$ref": "http://www.test.com/users/100001"
},
"primary": true
}
]
}
}
}
]
}
}
]
}
Replacing Existing Spend User Resources
Creates one or more provision requests using the /Bulk endpoint to replaces existing spend user resources.
PUT is used to replace an existing resource.
- We do not support an empty Spend User extension. However, if a PUT request is provided for an existing spend user with all blank fields, we will empty all other extensions and set the required fields to the default values.
Scopes
spend.user.general.writeonly - Refer to Scope Usage for full details.
Request
URI
Template
POST https://www.us.api.concursolutions.com/provisioning/v4/Bulk/
Parameters
None.
Headers
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN NamespaceContent-Typeis used to specify the nature of the data in the body of an entity, by giving type and subtype identifiers, and by providing auxiliary information that may be required for certain types (https://www.w3.org/Protocols/rfc1341/4_Content-Type.html)application/json,application/scim+json
Payload
Response
Status Codes
- 200 OK
- 400 Bad Request
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found
- 500 Internal Server Error
- 503 Service Unavailable
Headers
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7231 Content-Type
Payload
Examples
Request
- Note that UUID within the ID attribute and path must be included within the data of the request.
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:BulkRequest"
],
"failOnErrors": 1,
"Operations": [
{
"method": "PUT",
"path": "/Users/aaaaaaaa-bbbb-cccc-aaaa-bbbbbbbbbbb1",
"bulkId": "Seattle",
"data": {
"id": "aaaaaaaa-bbbb-cccc-aaaa-bbbbbbbbbbb1",
"userName": "john.doe21224@sap.com",
"active": false,
"name": {
"formatted": "Mr. John Doe",
"legalName": "Mr. John Doe",
"middleName": "Joe",
"middleInitial": "J",
"familyName": "Doe",
"givenName": "John",
"honorificPrefix": "Prof Dr Mr",
"honorificSuffix": "VI",
"hasNoMiddleName": true
},
"emails": [
{
"value": "john.doe193@sap.com",
"type": "work"
}
],
"entitlements": [
"Expense"
],
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"employeeNumber": "3749",
"companyId": "xxxxxxxx-xxx-xxx-xxx-9300b1c317xxx"
},
"urn:ietf:params:scim:schemas:extension:spend:2.0:User": {
"reimbursementCurrency": "USD",
"reimbursementType": "CONCUR_PAY",
"ledgerCode": "DEFAULT",
"country": "US",
"budgetCountryCode": "US",
"stateProvince": "WA",
"locale": "en-US",
"customData": [
{
"id": "custom1",
"value": "testing"
},
{
"id": "orgUnit2",
"value": "testSquadAlpha"
}
]
},
"urn:ietf:params:scim:schemas:extension:spend:2.0:Approver": {
"request": [
{
"approver": {
"employeeNumber": "requestApprover"
},
"primary": true
}
],
},
}
}
]
}
Schema
Spend User
| Name | Type | Format | Description |
|---|---|---|---|
reimbursementCurrency |
string |
- | Required Valid three digit currency code in the list of system reimbursement currencies. |
reimbursementType |
object |
- | Required The reimbursement type for the user. Supported values: ACCOUNTS_PAYABLE, ADP_PAYROLL, CONCUR_PAY, PAY_PAL, OTHER |
ledgerCode |
string |
- | Ledger code to associate with the user. |
country |
string |
- | Required Valid ISO 3166 country code. |
budgetCountryCode |
string |
- | Valid ISO 3166 country code for Budget. |
stateProvince |
string |
- | Valid ISO sub country code. Example: WA |
locale |
string |
- | Required Valid locale from the list of configured locales as defined in [RFC5646]. Example: en-US |
cashAdvanceAccountCode |
string |
- | Valid cash advance account code. |
testEmployee |
boolean |
true/false |
A Boolean value indicating whether the user is a test user. Can't be modified after the user is created. Can only be set at creation. |
nonEmployee |
boolean |
true/false |
A Boolean value indicating whether the user is a non-employee. |
biManager |
UserReference |
- | The UUID of the Reporting Manager. |
customData |
CustomData |
- | The Custom Data associated with this user. |
ADP Extension
| Name | Type | Format | Description |
|---|---|---|---|
adp |
ADP |
- | ADP settings for employee. |
Approver Extension
| Name | Type | Format | Description |
|---|---|---|---|
report |
SpendApprover |
- | A user's report approvers. |
cashAdvance |
SpendApprover |
- | A user's cash advance approvers. |
request |
SpendApprover |
- | A user's request approvers. |
invoice |
SpendApprover |
- | A user's invoice approvers. |
purchaseRequest |
SpendApprover |
- | A user's purchase request approvers. |
statement |
SpendApprover |
- | A user's statement approvers. |
budget |
SpendApprover |
- | A user's budget approvers. |
Delegate Extension
| Name | Type | Format | Description |
|---|---|---|---|
expense |
SpendDelegate | - | The user's expense delegates. |
payment |
SpendDelegate | - | The user's payment delegates. |
purchaseRequest |
SpendDelegate | - | The user's purchase request delegates. |
Spend Role
| Name | Type | Format | Description |
|---|---|---|---|
roles |
Role |
- | Expense roles for employee. |
User Preference Extension
| Name | Type | Format | Description |
|---|---|---|---|
showImagingIntro |
boolean |
true/false |
If true, displays imaging introduction. Default: true |
expenseAuditRequired |
string |
- | Expense audit is required. Supported values: NEVER, REQUIRED, ALWAYS |
allowCreditCardTransArrivalEmails |
boolean |
true/false |
If true, allows credit card transaction arrival notification emails. Default: true |
allowReceiptImageAvailEmails |
boolean |
true/false |
If true, allows credit card transaction arrival notification emails. Default: true |
promptForCardTransactionsOnReport |
boolean |
true/false |
If true, displays a prompt for company card transactions when creating a new report. Default: true |
autoAddTripCardTransOnReport |
boolean |
true/false |
If true, adds company card transactions within trip dates to one (1) click expense report. |
promptForReportPrintFormat |
boolean |
true/false |
If true, displays a prompt for the report format before printing. |
defaultReportPrintFormat |
string |
- | Default expense report print type. Supported values: RECEIPTS. DETAILED, FAX |
showTotalOnReport |
boolean |
true/false |
If true, displays report totals on detailed report. |
showExpenseOnReport |
string |
- | Show expenses on detailed report. Supported values: ALL, PARENT, NOTHING |
showInstructHelpPanel |
boolean |
true/false |
If true, displays instructional help. Default: true |
useQuickItinAsDefault |
boolean |
true/false |
If true, uses quick itinerary as default. |
Workflow Preferences Extension
| Name | Type | Format | Description |
|---|---|---|---|
emailStatusChangeOnCashAdvance |
boolean |
true/false |
If true, an email is sent when the cash advance status changes. Default: true |
emailAwaitApprovalOnCashAdvance |
boolean |
true/false |
If true, an email is sent when a cash advance is awaiting approval. Default: true |
emailStatusChangeOnReport |
boolean |
true/false |
If true, an email is sent when the report status changes. Default: true |
emailAwaitApprovalOnReport |
boolean |
true/false |
If true, an email is sent when a report is awaiting approval. Default: true |
promptForApproverOnReportSubmit |
boolean |
true/false |
If true, a prompt for approver is displayed when submitting a report. Default: false |
emailStatusChangeOnTravelRequest |
boolean |
true/false |
If true, an email is sent when the travel request status changes. Default: true |
emailAwaitApprovalOnTravelRequest |
boolean |
true/false |
If true, an email is sent when a travel request is awaiting approval. Default: true |
promptForApproverOnTravelRequestSubmit |
boolean |
true/false |
If true, a prompt for approver is displayed when submitting a travel request. Default: false |
emailStatusChangeOnPayment |
boolean |
true/false |
If true, an email is sent when the payment status changes. Default: true |
emailAwaitApprovalOnPayment |
boolean |
true/false |
If true, an email is sent when a payment is awaiting approval. Default: true |
promptForApproverOnPaymentSubmit |
boolean |
true/false |
If true, a prompt for approver is displayed when submitting a payment. Default: false |
User Reference
| Name | Type | Format | Description |
|---|---|---|---|
value |
string |
uuid |
The internal UUID identifier for the user. |
displayName |
string |
- | The username for the user. |
employeeNumber |
string |
- | The employee number for the user. |
$ref |
string |
uri |
The URI reference for the user. |
Custom Data
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
- | custom1 - custom22, orgUnit1 - orgUnit6 |
value |
string |
- | Value of the custom field. For list = List Item Code. |
ADP
| Name | Type | Format | Description |
|---|---|---|---|
companyCode |
string |
- | Required The company code for the employee within ADP. |
deductionCode |
string |
- | Required The deduction code for the employee within ADP. |
employeeFileNumber |
string |
- | Required The identifier for the employee within ADP, also known as the Employee File Number. |
Spend Approver
| Name | Type | Format | Description |
|---|---|---|---|
approver |
UserReference |
- | Required The UserReference of the approver. |
primary |
boolean |
true/false |
If true, the associated user is primary approver. |
Spend Delegate
| Name | Type | Format | Description |
|---|---|---|---|
canApprove |
boolean |
true/false |
If true, the delegate can approve. |
canPrepare |
boolean |
true/false |
If true, the delegate can prepare. |
canPrepareForApproval |
boolean |
true/false |
If true, the delegate can prepare for approval. |
canReceiveApprovalEmail |
boolean |
true/false |
If true, the delegate can receive approval emails. |
canReceiveEmail |
boolean |
true/false |
If true, the delegate can receive emails. |
canSubmit |
boolean |
true/false |
If true, the delegate can submit. |
canSubmitTravelRequest |
boolean |
true/false |
If true, the delegate can submit travel requests. |
canUseBi |
boolean |
true/false |
If true, the delegate can use BI. |
canViewReceipt |
boolean |
true/false |
If true, the delegate can view receipts. |
delegate |
UserReference |
- | The UserReference to the delegate. |
temporaryDelegation |
TemporaryDelegate |
- | Determines if delegate can temporarily approve. |
Temporary Delegate
| Name | Type | Format | Description |
|---|---|---|---|
temporaryDelegationFromDate |
string |
- | Start date for delegate's temporary approval permissions. |
temporaryDelegationToDate |
string |
- | End date for delegate's temporary approval permissions. |
Role
| Name | Type | Format | Description |
|---|---|---|---|
roleName |
string |
- | Required Expense role for employee. |
roleGroups |
string |
- | Required Group(s) to be associated with the Expense role. |
Spend User Retrieval
Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.
Limitations: This API is only available to partners who have been granted access. Access to this documentation does not provide access to the API.
Spend User Retrieval
Retrieving all Spend Users in a Company
Retrieves all the spend users for a given company. The result is paginated and can be filtered using the parameters listed below.
Scopes
spend.user.general.read - Refer to Scope Usage for full details.
Request
URI
Template
GET https://www.us.api.concursolutions.com/spend/v4/Users
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
startIndex |
integer |
startIndex >= 1 |
The starting index of the paginated result. |
itemsPerPage |
integer |
100 >= itemsPerPage >= 1 |
The number of user resources to return on a single page. |
filter |
string |
ABNF compliant | The SCIM compliant filter string to be used when retrieving user resources. |
Note: Not all aspects of SCIM filtering are supported. The following fields are implemented with the corresponding set of operators:
cashAdvanceAccountCode{ eq, ne }country{ eq, ne }customData{ complexValue that contains and, eq }ledgerCode{ eq, ne }locale{ eq, ne }nonEmployee{ eq, ne }reimbursementCurrency{ eq, ne }reimbursementType{ eq, ne }stateProvince{ eq, ne }testEmployee{ eq, ne }
Headers
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
Payload
None.
Response
Headers
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7231 Content-Type
Payload
Status Codes
- 200 OK
- 400 Bad Request
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found
- 500 Internal Server Error
- 503 Service Unavailable
Examples
Request
GET https://www.us.api.concursolutions.com/provisioning/v4/Users?&startIndex=1&itemsPerPage=4&filter=urn:ietf:params:scim:schemas:extension:spend:2.0:User:country+eq+%22US%22
Response
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"totalResults": 10000,
"Resources": [
{
"schemas": [
"urn:ietf:params:scim:schemas:extension:spend:2.0:Role",
"urn:ietf:params:scim:schemas:extension:spend:2.0:WorkflowPreference",
"urn:ietf:params:scim:schemas:extension:spend:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:Payroll",
"urn:ietf:params:scim:schemas:extension:spend:2.0:UserPreference",
"urn:ietf:params:scim:schemas:extension:spend:2.0:Approver",
"urn:ietf:params:scim:schemas:extension:spend:2.0:Delegate",
"urn:ietf:params:scim:schemas:ScimResource"
],
"id": "aaaaaaaa-xxxx-zzzz-xxxx-xxxxxxxxxxxx",
"urn:ietf:params:scim:schemas:extension:spend:2.0:Role": {
"roles": [
{
"roleName": "TRAVEL_USER"
}
]
},
"urn:ietf:params:scim:schemas:extension:spend:2.0:WorkflowPreference": {
"emailStatusChangeOnCashAdvance": false,
"emailAwaitApprovalOnCashAdvance": false,
"emailStatusChangeOnReport": false,
"emailAwaitApprovalOnReport": false,
"promptForApproverOnReportSubmit": false,
"emailStatusChangeOnTravelRequest": false,
"emailAwaitApprovalOnTravelRequest": false,
"promptForApproverOnTravelRequestSubmit": false,
"emailStatusChangeOnPayment": false,
"emailAwaitApprovalOnPayment": false,
"promptForApproverOnPaymentSubmit": false
},
"urn:ietf:params:scim:schemas:extension:spend:2.0:User": {
"reimbursementCurrency": "USD",
"reimbursementType": "CONCUR_PAY",
"country": "US",
"locale": "en-US",
"testEmployee": false,
"nonEmployee": false,
"customData": []
},
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:Payroll": {
"adp": {}
},
"urn:ietf:params:scim:schemas:extension:spend:2.0:UserPreference": {
"showImagingIntro": true,
"expenseAuditRequired": "REQUIRED",
"allowCreditCardTransArrivalEmails": true,
"allowReceiptImageAvailEmails": true,
"promptForCardTransactionsOnReport": true,
"autoAddTripCardTransOnReport": true,
"promptForReportPrintFormat": true,
"defaultReportPrintFormat": "RECEIPTS",
"showTotalOnReport": true,
"showExpenseOnReport": "PARENT",
"showInstructHelpPanel": true,
"useQuickItinAsDefault": false
},
"urn:ietf:params:scim:schemas:extension:spend:2.0:Approver": {},
"urn:ietf:params:scim:schemas:extension:spend:2.0:Delegate": {}
}
],
"startIndex": 1,
"itemsPerPage": 1
}
Retrieving a Spend User
Retrieves a specific user's spend data.
Scopes
spend.user.general.read - Refer to Scope Usage for full details.
Request
URI
Template
GET https://www.us.api.concursolutions.com/spend/v4/Users/{uuid}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
uuid |
string |
RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace | The unique identifier for the user that should be retrieved. |
Headers
concur-correlationidis a SAP Concur platform specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
Payload
None.
Response
Headers
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7231 Content-Type
Payload
Status Codes
- 200 OK
- 400 Bad Request
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found
- 500 Internal Server Error
- 503 Service Unavailable
Examples
Request
GET https://www.us.api.concursolutions.com/provisioning/v4/Users/aaaaaaaa-bbbb-cccc-aaaa-bbbbbbbbbbb1
Response
{
"schemas": [
"urn:com.concur.spend.user.model.scim.ScimResource",
"urn:ietf:params:scim:schemas:extension:spend:2.0:Role",
"urn:ietf:params:scim:schemas:extension:spend:2.0:WorkflowPreference",
"urn:ietf:params:scim:schemas:extension:spend:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:Payroll",
"urn:ietf:params:scim:schemas:extension:spend:2.0:UserPreference",
"urn:ietf:params:scim:schemas:extension:spend:2.0:Delegate",
"urn:ietf:params:scim:schemas:extension:spend:2.0:Approver"
],
"id": "aaaaaaaa-bbbb-cccc-aaaa-bbbbbbbbbbb1",
"urn:ietf:params:scim:schemas:extension:spend:2.0:Role": {
"roles": [
{
"roleName": "REQ_USER"
},
{
"roleName": "EXP_USER"
}
]
},
"urn:ietf:params:scim:schemas:extension:spend:2.0:WorkflowPreference": {
"emailStatusChangeOnCashAdvance": true,
"emailAwaitApprovalOnCashAdvance": true,
"emailStatusChangeOnReport": true,
"emailAwaitApprovalOnReport": true,
"promptForApproverOnReportSubmit": true,
"emailStatusChangeOnTravelRequest": true,
"emailAwaitApprovalOnTravelRequest": true,
"promptForApproverOnTravelRequestSubmit": true,
"emailStatusChangeOnPayment": true,
"emailAwaitApprovalOnPayment": true,
"promptForApproverOnPaymentSubmit": true
},
"urn:ietf:params:scim:schemas:extension:spend:2.0:User": {
"reimbursementCurrency": "USD",
"reimbursementType": "CONCUR_PAY",
"ledgerCode": "DEFAULT",
"country": "US",
"stateProvince": "WA",
"locale": "en-US",
"testEmployee": false,
"nonEmployee": false,
"customData": [
{
"id": "custom20",
"value": "testing"
},
{
"id": "custom9",
"value": "testing"
},
{
"id": "orgunit3",
"value": "testDepartment"
}
]
},
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:Payroll": {
"adp": {}
},
"urn:ietf:params:scim:schemas:extension:spend:2.0:UserPreference": {
"showImagingIntro": true,
"expenseAuditRequired": "REQUIRED",
"allowCreditCardTransArrivalEmails": true,
"allowReceiptImageAvailEmails": true,
"promptForCardTransactionsOnReport": true,
"autoAddTripCardTransOnReport": true,
"promptForReportPrintFormat": true,
"defaultReportPrintFormat": "DETAILED",
"showTotalOnReport": true,
"showExpenseOnReport": "ALL",
"showInstructHelpPanel": true,
"useQuickItinAsDefault": true
},
"urn:ietf:params:scim:schemas:extension:spend:2.0:Delegate": {
"expense": [
{
"canApprove": true,
"canPrepare": true,
"canPrepareForApproval": false,
"canReceiveApprovalEmail": true,
"canReceiveEmail": true,
"canSubmit": true,
"canSubmitTravelRequest": true,
"canUseBi": false,
"canViewReceipt": true,
"delegate": {
"value": "aaaaaaaa-bbbb-cccc-aaaa-bbbbbbbbbbb2"
}
}
]
},
"urn:ietf:params:scim:schemas:extension:spend:2.0:Approver": {
"request": [
{
"approver": {
"value": "aaaaaaaa-bbbb-cccc-aaaa-bbbbbbbbbbb2"
},
"primary": true
}
],
"report": [
{
"approver": {
"value": "aaaaaaaa-bbbb-cccc-aaaa-bbbbbbbbbbb2"
},
"primary": true
}
]
}
}
Schema
Spend User
| Name | Type | Format | Description |
|---|---|---|---|
reimbursementCurrency |
string |
- | Required Valid three digit currency code in the list of system reimbursement currencies. |
reimbursementType |
object |
- | Required The reimbursement type for the user. Supported values: ACCOUNTS_PAYABLE, ADP_PAYROLL, CONCUR_PAY, PAY_PAL, OTHER |
ledgerCode |
string |
- | Ledger code to associate with the user. |
country |
string |
- | Required Valid ISO 3166 country code. |
budgetCountryCode |
string |
- | Valid ISO 3166 country code for Budget. |
stateProvince |
string |
- | Valid ISO sub country code. Example: WA |
locale |
string |
- | Required Valid locale from the list of configured locales as defined in [RFC5646]. Example: en-US |
cashAdvanceAccountCode |
string |
- | Valid cash advance account code. |
testEmployee |
boolean |
true/false |
A Boolean value indicating whether the user is a test user. Can't be modified after the user is created. Can only be set at creation. |
nonEmployee |
boolean |
true/false |
A Boolean value indicating whether the user is a non-employee. |
biManager |
UserReference |
- | The UUID of the Reporting Manager. |
customData |
CustomData |
- | The Custom Data associated with this user. |
ADP Extension
| Name | Type | Format | Description |
|---|---|---|---|
adp |
ADP |
- | ADP settings for employee. |
Approver Extension
| Name | Type | Format | Description |
|---|---|---|---|
report |
SpendApprover |
- | A user's report approvers. |
cashAdvance |
SpendApprover |
- | A user's cash advance approvers. |
request |
SpendApprover |
- | A user's request approvers. |
invoice |
SpendApprover |
- | A user's invoice approvers. |
purchaseRequest |
SpendApprover |
- | A user's purchase request approvers. |
statement |
SpendApprover |
- | A user's statement approvers. |
budget |
SpendApprover |
- | A user's budget approvers. |
Delegate Extension
| Name | Type | Format | Description |
|---|---|---|---|
expense |
SpendDelegate | - | The user's expense delegates. |
payment |
SpendDelegate | - | The user's payment delegates. |
purchaseRequest |
SpendDelegate | - | The user's purchase request delegates. |
Spend Role
| Name | Type | Format | Description |
|---|---|---|---|
roles |
Role |
- | Expense roles for employee. |
User Preference Extension
| Name | Type | Format | Description |
|---|---|---|---|
showImagingIntro |
boolean |
true/false |
If true, displays imaging introduction. Default: true |
expenseAuditRequired |
string |
- | Expense audit is required. Supported values: NEVER, REQUIRED, ALWAYS |
allowCreditCardTransArrivalEmails |
boolean |
true/false |
If true, allows credit card transaction arrival notification emails. Default: true |
allowReceiptImageAvailEmails |
boolean |
true/false |
If true, allows credit card transaction arrival notification emails. Default: true |
promptForCardTransactionsOnReport |
boolean |
true/false |
If true, displays a prompt for company card transactions when creating a new report. Default: true |
autoAddTripCardTransOnReport |
boolean |
true/false |
If true, adds company card transactions within trip dates to one (1) click expense report. |
promptForReportPrintFormat |
boolean |
true/false |
If true, displays a prompt for the report format before printing. |
defaultReportPrintFormat |
string |
- | Default expense report print type. Supported values: RECEIPTS. DETAILED, FAX |
showTotalOnReport |
boolean |
true/false |
If true, displays report totals on detailed report. |
showExpenseOnReport |
string |
- | Show expenses on detailed report. Supported values: ALL, PARENT, NOTHING |
showInstructHelpPanel |
boolean |
true/false |
If true, displays instructional help. Default: true |
useQuickItinAsDefault |
boolean |
true/false |
If true, uses quick itinerary as default. |
Workflow Preferences Extension
| Name | Type | Format | Description |
|---|---|---|---|
emailStatusChangeOnCashAdvance |
boolean |
true/false |
If true, an email is sent when the cash advance status changes. Default: true |
emailAwaitApprovalOnCashAdvance |
boolean |
true/false |
If true, an email is sent when a cash advance is awaiting approval. Default: true |
emailStatusChangeOnReport |
boolean |
true/false |
If true, an email is sent when the report status changes. Default: true |
emailAwaitApprovalOnReport |
boolean |
true/false |
If true, an email is sent when a report is awaiting approval. Default: true |
promptForApproverOnReportSubmit |
boolean |
true/false |
If true, a prompt for approver is displayed when submitting a report. Default: false |
emailStatusChangeOnTravelRequest |
boolean |
true/false |
If true, an email is sent when the travel request status changes. Default: true |
emailAwaitApprovalOnTravelRequest |
boolean |
true/false |
If true, an email is sent when a travel request is awaiting approval. Default: true |
promptForApproverOnTravelRequestSubmit |
boolean |
true/false |
If true, a prompt for approver is displayed when submitting a travel request. Default: false |
emailStatusChangeOnPayment |
boolean |
true/false |
If true, an email is sent when the payment status changes. Default: true |
emailAwaitApprovalOnPayment |
boolean |
true/false |
If true, an email is sent when a payment is awaiting approval. Default: true |
promptForApproverOnPaymentSubmit |
boolean |
true/false |
If true, a prompt for approver is displayed when submitting a payment. Default: false |
User Reference
| Name | Type | Format | Description |
|---|---|---|---|
value |
string |
uuid |
The internal UUID identifier for the user. |
displayName |
string |
- | The username for the user. |
employeeNumber |
string |
- | The employee number for the user. |
$ref |
string |
uri |
The URI reference for the user. |
Custom Data
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
- | custom1 - custom22, orgUnit1 - orgUnit6 |
value |
string |
- | Value of the custom field. For list = List Item Code. |
ADP
| Name | Type | Format | Description |
|---|---|---|---|
companyCode |
string |
- | Required The company code for the employee within ADP. |
deductionCode |
string |
- | Required The deduction code for the employee within ADP. |
employeeFileNumber |
string |
- | Required The identifier for the employee within ADP, also known as the Employee File Number. |
Spend Approver
| Name | Type | Format | Description |
|---|---|---|---|
approver |
UserReference |
- | Required The UserReference of the approver. |
primary |
boolean |
true/false |
If true, the associated user is primary approver. |
Spend Delegate
| Name | Type | Format | Description |
|---|---|---|---|
canApprove |
boolean |
true/false |
If true, the delegate can approve. |
canPrepare |
boolean |
true/false |
If true, the delegate can prepare. |
canPrepareForApproval |
boolean |
true/false |
If true, the delegate can prepare for approval. |
canReceiveApprovalEmail |
boolean |
true/false |
If true, the delegate can receive approval emails. |
canReceiveEmail |
boolean |
true/false |
If true, the delegate can receive emails. |
canSubmit |
boolean |
true/false |
If true, the delegate can submit. |
canSubmitTravelRequest |
boolean |
true/false |
If true, the delegate can submit travel requests. |
canUseBi |
boolean |
true/false |
If true, the delegate can use BI. |
canViewReceipt |
boolean |
true/false |
If true, the delegate can view receipts. |
delegate |
UserReference |
- | The UserReference to the delegate. |
temporaryDelegation |
TemporaryDelegate |
- | Determines if delegate can temporarily approve. |
Temporary Delegate
| Name | Type | Format | Description |
|---|---|---|---|
temporaryDelegationFromDate |
string |
- | Start date for delegate's temporary approval permissions. |
temporaryDelegationToDate |
string |
- | End date for delegate's temporary approval permissions. |
Role
| Name | Type | Format | Description |
|---|---|---|---|
roleName |
string |
- | Required Expense role for employee. |
roleGroups |
string |
- | Required Group(s) to be associated with the Expense role. |
List Response
| Name | Type | Format | Description |
|---|---|---|---|
schemas |
string |
- | The schemas present in the resource. |
totalResults |
integer |
int32 |
Required The total number of results returned by the list or query operation. |
Resources |
FullSpendUser |
- | A multi-valued list of complex objects containing the requested resources. |
startIndex |
integer |
int32 |
The 1-based index of the first result in the current set of list results. |
itemsPerPage |
integer |
int32 |
The number of resources returned in a list response page. |
Full Spend User
| Name | Type | Format | Description |
|---|---|---|---|
schemas |
string |
- | The schemas present in the resource. |
urn:ietf:params:scim:schemas:extension:spend:2.0:Approver |
ApproverExtension |
- | The user's spend approver data. |
urn:ietf:params:scim:schemas:extension:spend:2.0:Delegate |
DelegateExtension |
- | The user's spend delegate data. |
urn:ietf:params:scim:schemas:extension:spend:2.0:Role |
SpendRole |
- | The user's spend role data. |
urn:ietf:params:scim:schemas:extension:spend:2.0:UserPreference |
UserPreferenceExtension |
- | The user's user preference settings. |
urn:ietf:params:scim:schemas:extension:enterprise:2.0:Payroll |
ADPExtension |
- | The user's ADP data. |
urn:ietf:params:scim:schemas:extension:spend:2.0:WorkflowPreference |
WorkflowPreferenceExtension |
- | The user's workflow preference settings. |
Error Message Response
| Name | Type | Format | Description |
|---|---|---|---|
schemas |
string |
- | The schemas present in this resource. |
scimType |
string |
- | A SCIM detailed error keyword. |
detail |
string |
- | A detailed, human readable message. |
status |
integer |
int32 |
The HTTP status code. |
Spend Role Codes
Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.
- Column Description
- Expense Product Roles
- Request Product Roles
- Invoice (Payment) Product Roles
- Reporting Product Roles
Column Description
| Role Code | Role Full Name | Description | Group-Aware | Product Area |
|---|---|---|---|---|
The role code value that can be used for provisioning with the Spend Role Extension. |
The full name of the role. | The usage of the role. | When assigning this role, one or more groups must be given. | Shared with two or more SAP Concur products. |
Expense Product Roles
| Role Code | Role Full Name | Description | Group-Aware | Product Area |
|---|---|---|---|---|
SHD_APP_CENTER_ADMIN |
App Center Listing Administrator | The user assigned this role can submit App Center listings. This role is only assigned by SAP Concur to certain App Center partners. | N | Y |
EXP_ATTENDEE_ADMIN |
Attendee Administrator | The user assigned this role can view, modify, and activate or inactivate any attendee record in the system. | Y | Y |
EXP_ATTENDEE_ADMIN_RO |
Attendee Administrator (Read only) | The user assigned this role is considered a read-only auditor. The user can access and view but not modify and activate or inactivate an attendee record in the system. | Y | Y |
SHD_AUTHORIZED_APPROVER |
Authorized Approver | This is special approver role. The user assigned this role can approve, with a specified limit, specific expense reports. | N | N |
N/A |
Account Code Administrator | NOTE: This field is not supported. | N | N |
EXP_AUTH_REQUEST_ADMIN |
Authorization Request Administrator | The user assigned this role can view and update authorization requests in Authorization Administrator. | Y | N |
EXP_AUTH_REQUEST_APPROVER |
Authorization Request Approver | The user assigned this role can approve authorization requests in Expense Reports. | N | N |
SHD_BILLING_ATTRIBUTES_USER |
Billing Attributes User | The user assigned this role can manage billing related settings for the entity. | N | Y |
SHD_BUDGET_ADMIN |
Budget Administrator | For Budget Insight (Legacy): The user assigned this role can set budget amounts and assign budget approvers. For Budget: The user assigned this role can configure the Fiscal Calendar, Budget Categories, Budget Tracking Fields, Budget Items, and Budget Settings. The Budget Administrator can see the budget amounts as configured in the Budget Items, but not the budget actuals as is shown in the dashboards. Budget Administrators have access to all budget items within an entity. |
N | Y |
SHD_BUDGET_APPROVER |
Budget Approver/Manager | For Budget Insight (Legacy): The user assigned this role can review and approve expense reports using real-time budget figures. For Budget: The user assigned this role can approve invoices, purchase requests, and expense reports and can view budgets in the budget dashboards. The Budget Approver does not have access to the budget configuration information. |
N | Y |
SHD_BUDGET_OWNER |
Budget Owner | The user assigned this role owns the budget and can view budgets in the dashboards. The Budget Owner does not have access to the budget configuration information. | N | Y |
SHD_BUDGET_VIEWER |
Budget Viewer | The user assigned this role views budgets in the dashboards. There can be one or several budget viewers. The Budget Viewer does not have access to the budget configuration information. | N | Y |
EXP_PCARD_ADMIN |
Card Program Administrator | The user assigned this role manages the company's purchase card program and statement periods. | Y | N |
EXP_PROCESSOR_CR |
Central Reconciliation Processor | The user assigned this role processes (matches) invoice transactions associated with requests generated within the Request product. | Y | N |
TRAVEL_USER |
Cliqbook User | The user assigned this role can integrate with Cliqbook service. | N | N |
EXP_CONFIG_ADMIN_CLIENT |
Client Expense Administrator | This custom role is not available to all clients; availability is based on the client configuration. This field combines permissions from the Expense Configuration Administrator role and the Shared Configuration Administrator. The user assigned this role can access these options (some may allow add/edit; some may be view-only): Accounting administration, audit rules, car configuration, email reminders, exceptions, expense types, locations, policies, travel allowance, workflows. | Y | N |
STATEMENT_APPROVER |
Company Bill Statement Approver | The user assigned this role approves statement reports. This user must also be assigned the Expense Approver role. | N | N |
STATEMENT_PROCESSOR |
Company Bill Statement Processor | The user assigned this role views and updates statement reports in Expense Processor. This user must also be assigned the Expense Processor role. | Y | N |
STATEMENT_PROCESSOR_AUDITOR |
Company Bill Statement Processor (Audit) | The user assigned this role views statement reports in Expense Processor in read-only format. This user must also be assigned the Expense Processor (Audit) role. | N | - |
STATEMENT_PROCESSOR_ADMIN |
Company Bill Statement Processor Manager | The user assigned this role views, updates, and deletes statement reports in Expense Processor. This user must also be assigned the Expense Processor Manager role. | Y | N |
STATEMENT_USER |
Company Bill Statement User | The user assigned this role reviews and submits the purchasing card transactions in the statement reports. This user must also be assigned the Expense User role. | N | N |
SHD_COMPANY_INFO_ADMIN |
Company Info Administrator | The user assigned this role can update the Company Info section of the home page. | N | Y |
N/A |
Concur Mobile User | NOTE: This field is not supported. | N | N/A |
SHD_COST_OBJECT_APPROVER |
Cost Object Approver | This is special approver role, which is not assigned the same way as other roles. | N | N |
SHD_DATA_RETENTION_ADMIN |
Data Retention Administrator | The user assigned this role views and configures the data retention policy for the company and can hold and purge individual users. | N | Y |
N/A |
Digital Compliance Administrator | NOTE: This field is not supported. | N | N |
SHD_EMPLOYEE_ADMIN |
Employee Administrator | The user assigned this role can add and manage employees, including assigning roles, delegates, and preferences. The user can only assign the basic user roles (Expense User, Travel User), using the check boxes on the User Details page. They may also view and optionally edit and register cars on behalf of a user. | Y | Y |
SHD_EMPLOYEE_ADMIN_RO |
Employee Administrator (Read Only) | The user assigned this role is considered a read-only auditor. The user can view but not add or edit employee records. | N | Y |
N/A |
Employee Maintenance | NOTE: This field is not supported. | Y | Y |
EXP_APPROVER |
Expense Approver | The user assigned this role can approve expense reports within an assigned group. | N | N |
EXP_CASHADVANCE_ADMIN |
Expense Cash Advance Administrator | The user assigned this role can view, issue, and manage cash advance requests. | Y | N |
EXP_CARD_ADMIN |
Expense Company Card Administrator | The user assigned this role can assign and unassign company cards, and map expense types to merchant category codes. | Y | N |
EXP_CONFIG_ADMIN |
Expense Configuration Administrator | This role is intended to be assigned to and used by SAP Concur internal staff only, with few exceptions. The user assigned this role can fully manage (add, edit, delete) Expense group configurations, Policies, Expense-based forms and fields, validations, and vendor lists, Expense report and authorized approver workflows, Audit rules, Expense types and expense categories, Payment types, Account codes, Exceptions, Car configuration and reimbursement, Receipt handling, including payment hold, scan configurations, receipt limits, and receipt imaging, Email reminders, Reimbursement currencies, Offline settings, Configuration change log (view only), Taxability and Deductibility Calculation Service. NOTE: A user cannot be assigned the EXP_CONFIG_ADMIN and the EXP_CONFIG_ADMIN_RO. |
Y | N |
EXP_CONFIG_ADMIN_RO |
Expense Configuration Administrator (Restricted) | The user assigned this role can fully manage (add, edit, delete) vendor list items, authorized approvers, audit rules, account codes, exceptions, personal and company car rates, receipt handling including receipt limits, payment hold, and scan configurations, email reminders, configuration change log (view only), taxability and deductibility calculation service. | Y | N |
EXP_PROCESSOR |
Expense Processor | The user assigned this role can view and update expense reports within Expense Processor. The Access for Processor field limits the reports the processor can view to all reports excluding returned reports, all reports including returned reports, or only reports pending processor step and beyond. NOTE: The user should only be assigned one of the Expense Processor roles. If the user is assigned multiple Expense Processor roles, the role with the greatest level of access will be applied. The levels of access, from highest to lowest, are: Expense Processor Manager (1), Expense Processor (2), Expense Processor (Audit) (3). |
Y | N |
EXP_PROCESSOR_AUDIT |
Expense Processor (Audit) | The user assigned this role can view expense reports within Expense Processor. NOTE: The user should only be assigned one of the Expense Processor roles. If the user is assigned multiple Expense Processor roles, the role with the greatest level of access will be applied. The levels of access, from highest to lowest, are: Expense Processor Manager (1), Expense Processor (2), Expense Processor (Audit) (3). |
Y | N |
EXP_PROCESSOR_ADMIN |
Expense Processor Manager | The user assigned this role can view, update, and delete expense reports within Expense Processor. The Access for Processor field limits the reports the processor can view all reports excluding returned reports, all reports including returned reports, or only reports pending processor step and beyond. NOTE: The user should only be assigned one of the Expense Processor roles. If the user is assigned multiple Expense Processor roles, the role with the greatest level of access will be applied. The levels of access, from highest to lowest, are: Expense Processor Manager (1), Expense Processor (2), Expense Processor (Audit) (3). |
Y | N |
EXP_PROXY_USER |
Expense Proxy Logon | The user assigned this role can log on to Expense and act as a proxy user for other employees within an assigned group. | Y | N |
EXP_RECEIPT_PROCESSOR |
Expense Receipt Processor | The user assigned this role can update the receipt status for an expense report. | N | N |
N/A |
Expense Type Administrator | NOTE: This field is not supported. | N | N |
EXP_USER |
Expense User | The user assigned this role can create and submit expense reports and cash advances if those features are used by the user's company. | N | N |
EXP_EMPLOYEE_ADMIN |
Employee Admin Permission on Expense Hierarchy | Can grant Expense Hierarchy Nodes permission to users in the Employee Admin. NOTE: Each user assigned Employee admin must also be assigned permissions for reporting (BI), expense, and payment (Invoice). These additional permissions govern the roles the employee administrator can assign for the employees in his or her assigned groups. |
Y | N |
EXP_FIND_ATTENDEES_USER |
Employee (while finding attendees) | Role code to determine the field access while searching attendees. | N | N |
EXP_EXTRACT_ADMIN |
Extract Administrator | Special role assigned by the SAP Concur Implementation department to clients who are transitioning from the Standard Edition to the Professional Edition. This role provides access to the File Export Configuration tool. | N | N |
N/A |
Expense Processor(Concur Audit) | NOTE: This field is not supported. | N | N |
EXP_FB_TAX_ADMIN |
Fringe Benefits Tax Administrator | Along with the Tax Administration role, the user assigned this role can manage fringe-benefit tax. | N | N |
SHD_IMPORT_EXTRACT_ADMIN_RO |
Import/Extract Monitor (formerly Integration Administrator - Restricted) | A user assigned this role can view details of import, extract, archive, and reporting consolidation jobs, job schedule, system logs. Depending on configuration, this user may also be able to upload import files, and download extract files. | N | Y |
SHD_PASSWORD_ADMIN |
Password Manager | The user assigned this role can update passwords for Expense users. User will have read only access to the following fields on the User Details page in User Administration: Title, First Name, Middle Name, Nickname, Last Name, Suffix, and Email. Preventing Access: A module property is available to restrict this role from changing password. Please contact SAP Concur directly to have the Password Access Restriction feature activated. NOTE: The users with Expense and either Travel or Invoice have one password for all applications. When any of the Password Manager roles changes a password, it changes for all. |
Y | Y |
EXP_REIMBURSEMENT_AUDITOR |
Reimbursement Auditor | A user assigned this role can view Expense Pay functionality: Funding Accounts, Batch Configurations, Card Programs, Expense Pay Settings, Current and Historical Batch List, Daily Funding and Returned Amounts, Payment Demand List, Report Payees List, and Employee Banking Status | N | Y |
EXP_REIMBURSEMENT_APPROVER |
Reimbursement Manager | A user assigned this role can fully manage (add, edit, delete) Expense Pay functionality: Funding Accounts, Batch Configurations, Card Programs, and Expense Pay Settings. In addition, a user assigned this role can view the following Expense Pay details: Current and Historical Batch List, Daily Funding and Returned Amounts, Payment Demand List, and Report Payees List. Only global Reimbursement Managers can create and view payment demands: Employee Banking Status |
Y | Y |
SHD_ROLE_ADMIN |
Role Administrator | A user assigned this role is granted access to the Expense, Invoice, and Request tabs through User Permissions. | Y | Y |
N/A |
Role Builder | This role is intended to be assigned to and used by SAP Concur internal staff only. | N | Y |
SHD_CONFIG_ADMIN |
Shared Configuration Administrator | This role is intended to be assigned to and used by SAP Concur internal staff only, with few exceptions. The user assigned this role can fully manage (add, edit, delete) Feature hierarchies for Expense Reports and Vendor Invoices, Employee group configurations, including assignment of the employee form, Employee forms and fields, validations, and custom and connected lists, Expense and payment delegate configurations, Reimbursement currencies, Imaging settings, Accounting structure (ledgers), Localization tasks, Configuration change log (view only). Hierarchy segment values are used to identify the hierarchy node for which this employee has approval rights. If blank, resolves to the global group. NOTE: A user cannot be assigned the SHD_CONFIG_ADMIN and the SHD_CONFIG_ADMIN_RO. |
Y | Y |
SHD_CONFIG_ADMIN_RO |
Shared Configuration Administrator (Restricted) | The user assigned this role can access locations (add or edit), view, add, edit, and delete custom list items, and view the configuration change log. | Y | Y |
SHD_TAX_ADMIN |
Tax Administrator | The user assigned this role can fully manage (add, edit, delete) value added tax (VAT) tax configurations, and rates. | N | N |
SHD_TAX_ADMIN_RO |
Tax Administrator (Restricted) | The user assigned this role can view tax configurations. | N | N |
SHD_TRAINING_ADMIN |
Training Administrator | The user assigned this role can access the Training Administration tool to configure client-preferred Training landing page and the contents and contact information that displays. | N | Y |
N/A |
Travel and Expense Pilot User | Do not use: this role is retired. | N/A | N/A |
EXP_TRAVEL_AND_EXPENSE_USER |
Travel and Expense User | NOTE: This field is not supported. | N | Y |
N/A |
UI Preview | NOTE: This field is not supported. | N | Y |
SHD_WEB_SERVICES_ADMIN |
Web Services Administrator | The user assigned this role can access the Partner Application Administration page to register or enable partner applications to access the company’s data using the SAP Concur web services. The partner applications are required for some integrations, and do not appear in the SAP Concur App Center. They may also access the Manage User Apps page to restrict the User applications in the SAP Concur App Center for their company's users, as well as Enable Enterprise partner applications within the SAP Concur App Center. | N | SAP Concur Connect |
Request Product Roles
| Role Code | Role Full Name | Description | Group-Aware | Product Area |
|---|---|---|---|---|
SHD_DATA_RETENTION_ADMIN |
Data Retention Administrator | The user assigned this role views and configures the data retention policy for the company and can hold and purge individual users. | N | Y |
REQ_PROCESSOR_ADMIN |
Request Administrator | This is one of the Request processor roles. The user assigned this role can view and fully manage virtually all requests. |
Y | N |
REQ_APPROVER |
Request Approver | The user assigned this role can approve requests within their assigned group. | N | N |
REQ_PROCESSOR_AUDIT |
Request Auditor | This is one of the Request processor roles. This is a read-only role. The SAP Concur client can assign this role to TMCs, to its own internal travel agent(s), or to any other user that needs read-only access to requests. |
Y | N |
REQ_CONFIG_ADMIN |
Request Configuration Administrator | This role is intended to be assigned to and used by SAP Concur internal staff only, with few exceptions. The user assigned this role can fully manage (add, edit, delete) all request-related features on the Request Admin menu. NOTE: A user cannot be assigned the REQ_CONFIG_ADMIN and the REQ_CONFIG_ADMIN_RO. |
Y | N |
REQ_CONFIG_ADMIN_RO |
Request Configuration Administrator (restricted) | The user assigned this role can fully manage (add, edit, delete) list management, locations, segment types, and travel agency offices | Y | N |
REQ_EVENT_ADMIN |
Request Event Manager | The user assigned this role can create a primary event request for multiple event attendees. This role must be assigned with the Request Proxy Logon role. |
N | N |
REQ_PROXY_USER |
Request Proxy Logon | The user assigned this role can log on to Request and act as a proxy user for other employees within an assigned group. | Y | N |
REQ_USER |
Request User | The user assigned this role can create and submit requests. | N | N |
REQ_RISK_ADMIN |
Risk Manager | This permission appears only if Request is integrated with Concur Risk Management. The user assigned this role can process requests waiting for Risk Manager processing and view submitted requests with risk. NOTE: A user cannot be assigned this role and one of the other Request processor roles. |
Y | N |
REQ_PROCESSOR |
TMC Agent | This is one of the Request processor roles. The SAP Concur client assigns this role to one or more agents of its Travel Management Company (TMC) or to the client's internal travel agent(s). In some regions, it is appropriate for the TMC Agent to access the request after the user submits it but before the approver receives it. This way, the TMC Agent can add/edit the segment amounts – ensuring accuracy for the request approver. |
Y | N |
Invoice (Payment) Product Roles
| Role Code | Role Full Name | Description | Group-Aware | Product Area |
|---|---|---|---|---|
SHD_BUDGET_ADMIN |
Budget Administrator | The user assigned this role can configure the Fiscal Calendar, Budget Categories, Budget Tracking Fields, Budget Items, and Budget Settings. The Budget Administrator can see the budget amounts as configured in the Budget Items, but not the budget actuals as is shown in the dashboards. Budget Administrators have access to all budget items within an entity. | N | Y |
SHD_BUDGET_APPROVER |
Budget Approver/Manager | The user assigned this role can approve invoices, purchase requests, and expense reports and can view budgets in the budget dashboards. The Budget Approver does not have access to the budget configuration information. | N | Y |
SHD_BUDGET_OWNER |
Budget Owner | The user assigned this role owns the budget and can view budgets in the dashboards. The Budget Owner does not have access to the budget configuration information. | N | Y |
SHD_BUDGET_VIEWER |
Budget Viewer | The user assigned this role views budgets in the dashboards. There can be one or several budget viewers. The Budget Viewer does not have access to the budget configuration information. | N | Y |
INV_PURCH_RECEIVER |
Central Receiver | The user assigned this role can add, edit, and delete purchase order receipts and receipt images. However, they cannot transmit or process purchase orders or invoices. | Y | N |
INV_IC_VERIFIER |
Client Managed Capture Verifier | The user assigned this role can verify the output of invoices in the client-managed version of Capture Processing. | N | N |
SHD_DATA_RETENTION_ADMIN |
Data Retention Administrator | The user is assigned this role views and configures the data retention policy for the company and can hold and purge individual users. | N | Y |
INV_EMPLOYEE_ADMIN |
Employee Admin Permission on Invoice Hierarchy | The user assigned this role can grant Invoice Hierarchy Nodes permission to users in the Employee Admin. NOTE: Each user assigned employee admin must also be assigned permissions for reporting (BI), expense, and payment (Invoice). These additional permissions govern the roles the employee administrator can assign for the employees in his or her assigned groups. |
Y | N |
INV_AP_USER |
Invoice AP User | The user assigned this role can create, assign, and reassign invoices. They can also reassign a different policy to an invoice and restore deleted invoices. | Y | N |
INV_APPROVER |
Invoice Approver | The user assigned this role can to approve invoices within an assigned group. | N | N |
INV_CONFIG_ADMIN |
Invoice(Payment) Configuration Administrator | This role is intended to be assigned to and used by SAP Concur internal staff only, with few exceptions. The user assigned this role can fully manage (add, edit, delete) Invoice group configurations, Policies, Invoice-based forms, fields, and validations, Invoice and authorized approver workflows, Audit rules, Expense types, Account codes and account code hierarchy, Exceptions, Image handling, including scan configurations, invoice imaging, vendor imaging, Email reminders, Company Info, Configuration change log (view only). NOTE: A user cannot be assigned the INV_CONFIG_ADMIN and the INV_CONFIG_ADMIN_RO. |
Y | N |
INV_CONFIG_ADMIN_RO |
Invoice (Payment) Configuration Administrator (Restricted) | The user assigned this role can fully manage (add, edit, delete) authorized approvers, audit rules, account codes, exceptions, expense types, scan configurations, email reminders, and configuration change log (view only). | Y | N |
N/A |
Invoice Full User | NOTE: This field is not supported. | N | N |
N/A |
Invoice Pilot User | NOTE: This field is not supported. | N | N |
INV_PMT_MANAGER |
Invoice Payment Manager | A user assigned this role can fully manage (add, edit, delete) Invoice Pay functionality. This user can monitor and adjust Invoice Pay batches and invoices scheduled for payment and define the Checking and ACH funding accounts that are used for payment. | N | N |
INV_IMAGE_PROCESSOR |
Invoice Image Processor | The user assigned this role can update the status of receipt and invoice images. | N | N |
INV_PROCESSOR |
Invoice(Payment) Processor | The user assigned this role an view and update invoices within Invoice Processor. They may also assign or reassign invoices, and restore deleted invoices. NOTE: The user should only be assigned one of the Invoice Processor roles. If the user is assigned multiple Invoice Processor roles, the role with the least level of access will be applied. The levels of access, from highest to lowest, are: Invoice Processor Manager (1), Invoice Processor (2), Invoice Processor (Audit) (3) |
Y | N |
INV_PROCESSOR_AUDIT |
Invoice(Payment) Processor (Audit) | The user assigned this role can view invoices within Invoice Processor. NOTE: A user cannot be assigned the Processor Audit role and any other Invoice (Payment) processor role. |
Y | N |
INV_PROCESSOR_MANAGER |
Invoice(Payment) Processor Manager | The user assigned this role can view, update, and delete invoices within Invoice Processor. NOTE: A user cannot be assigned the Invoice (Payment) Processor Manager role and an audit role. |
Y | N |
INV_PROXY_USER |
Invoice(Payment) Proxy Logon | The user assigned this role can log on to Vendor Invoices and act as a proxy user for other employees within an assigned group. | Y | N |
INV_PURCH_USER |
Invoice Purchasing User | The user assigned this role cannot create and submit invoices but can be granted rights to change form field values to adjust totals, etc. in Invoice Purchase Order. NOTE: This role is available only to users of Invoice. |
N | N |
INV_RECEIPT_PROCESSOR |
Invoice(Payment) Receipt Processor | The user assigned this role can view and update invoices in Invoice Received status within Invoice Processor. | Y | N |
INV_TAX_ADMIN |
Invoice Tax Administrator | The user assigned this role can configure and activate the Tax Administration tool. | N | N |
INV_PMT_USER |
Invoice User | The user assigned this role can create and submit invoices. | N | N |
INV_VENDOR_ADMIN |
Invoice Vendor Manager | The user assigned this role can work with vendors, including approving new vendors, working with the master list, and mapping vendors. | Y | N |
INV_PURCH_ORDER_PROCESSOR |
Purchase Order Processor | The user assigned this role can process purchase orders in the Purchase Request module. | Y | N |
INV_PURCH_ORDER_PROCESSOR_AUDIT |
Purchase Order Processor (Audit) | The user assigned this role can view purchase orders within the purchase order processor and can view receipts within the purchase order processor. receipts. | Y | N |
INV_PURCH_REQ_APPROVER |
Purchase Request Approver | The user assigned this role can approve purchase requests in the Purchase Request module. | N | N |
INV_PURCH_REQ_PROCESSOR |
Purchase Request Processor | The user assigned this role can process purchase requests in the Purchase Request module. | Y | N |
INV_PURCH_REQ_PROCESSOR_AUDIT |
Purchase Request Processor (Audit) | The user assigned this role can view purchase requests within the purchase request processor. | Y | N |
INV_PURCH_REQ_PROXY_USER |
Purchase Request Proxy Logon | The user assigned this role can log on to Purchase Request and act as a proxy user for other employees within an assigned group. NOTE: This role may proxy for any user assigned the Purchase Request User role. |
Y | N |
INV_PURCH_REQ_USER |
Purchase Request User | The user assigned this role can create purchase requests in the Purchase Request module. | N | N |
INV_RECEIPT_USER |
Receipt User | The user assigned this role can enter, update, and delete receipt data for their own purchase orders. | N | N |
Reporting Product Roles
| Role Code | Role Full Name | Description | Group-Aware | Product Area |
|---|---|---|---|---|
BUDGET_REPORTING_USER |
Budget Role for Cognos | The user assigned this role can access the Budget module in the Analysis/Intelligence data model. | Y | N |
REPORTING_CAS_ANALYST |
CAS Analyst | NOTE: Do not use. This role is retired. | Y | N |
REPORTING_BUSINESS_AUTHOR |
Cognos Business Author | The user assigned this role can use Analysis/Intelligence to view data for reports submitted at all hierarchical levels within their assigned groups (as well as any data not group-related). The user is assigned the Business license type, which restricts the features to which they have access. They may also run existing reports, create new reports or modify existing basic reports using the basic tool, Query Studio. NOTE: A user cannot be assigned this role and the Cognos Professional Author or Cognos Consumer roles, only one of these three may be assigned. |
Y | N |
REPORTING_CONSUMER |
Cognos Consumer | The user assigned this role can use Analysis/Intelligence to view data for reports submitted at all hierarchical levels within their assigned groups (as well as any data not group-related). The user is assigned the Consumer license type, which further restricts the features to which they have access. They may also run existing reports, with read-only access. NOTE: A user cannot be assigned this role and the Cognos Professional Author or Cognos Business Author roles, only one of these three may be assigned. |
Y | N |
REPORTING_PRO_AUTHOR |
Cognos Professional Author | The user assigned this role can use Analysis/Intelligence to view data for reports submitted at all hierarchical levels (no group assignment required). The user is assigned the Professional license type, which allows access to all features. They may also run existing reports, create new reports or modify existing basic reports using the basic tool, Query Studio, and create new reports or modify existing basic reports using the advanced tool, Report Studio. They can also schedule automatic report runs. | Y | N |
REPORTING_CONFIG_ADMIN |
Consolidation Configuration Administrator | This role is used by companies using the Reporting Database that wish to consolidate the data from the current version and previous versions. The user assigned this role can map expense types and custom fields to a single consolidated definition, and adjust other consolidation settings. NOTE: This role does not include access to Analysis/Intelligence. |
N | N |
REPORTING_HIST_DATA_USER |
Cognos Hist Data Access | Cognos Hist Data Access. | N | N |
REPORTING_DASHBOARD_USER |
Dashboard User | NOTE: Do not use. This role is retired. | N | N |
REPORTING_EMPLOYEE_ADMIN |
Employee Admin Permission on Reporting Hierarchy | The user assigned this role can grant Reporting Hierarchy Nodes permission to users in the Employee Admin. NOTE: Each user assigned Employee admin must also be assigned permissions for reporting (BI), expense, and payment (Invoice). These additional permissions govern the roles the employee administrator can assign for the employees in his or her assigned groups. |
Y | N |
Travel Extension v4
Important: This API is currently in pre-release status and is only available to approved early access participants. The API is under development and might change before being generally released. To become an early access participant, contact your SAP Concur Representative.
This endpoint is available to clients and partners who utilize User Provisioning v4 to provision or modify users in the Concur Travel extension. It allows callers to retrieve values for the Concur Travel user that have been provisioned via User Provisioning. For partners or TMCs who need to retrieve additional Travel Profile data that is not supported here, please use Travel Profile v2 API.
Limitations: This API is only available to partners who have been granted access by SAP Concur. Access to this documentation does not provide access to the API.
- Products and Editions
- Scope Usage
- Dependencies
- Access Token Usage
- Retrieve Travel User Data
- Schema
- Definitions
Products and Editions
- Concur Travel Professional Edition
- Concur Travel Standard Edition
Scope Usage
| Name | Description | Endpoint |
|---|---|---|
travel.user.general.read |
Reads general data. | GET |
travel.user.private.read |
Reads private data. | GET |
Dependencies
SAP Concur clients must use the User Provisioning v4 API to provision users in order to use this endpoint to retrieve user data.
Access Token Usage
This API supports only company access tokens.
Retrieve Travel User Data
Retrieves the information of a SAP Concur Travel user.
Scopes
-
travel.user.general.read- Refer to Scope Usage for full details. -
travel.user.private.read- Refer to Scope Usage for full details.
Request
URI
Template
GET /travel/v4/Users
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
UUID |
The SAP Concur UUID of the user. |
Headers
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN NamespaceContent-Typeis used to specify the nature of the data in the body of an entity, by giving type and subtype identifiers, and by providing auxiliary information that may be required for certain types (https://www.w3.org/Protocols/rfc1341/4_Content-Type.html)application/json,application/scim+json
Response
Status Codes
- 200 OK
- 400 Bad Request
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found
- 500 Internal Server Error
- 503 Service Unavailable
Headers
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7231 Content-Type
- RFC 7231 Content-Encoding
- RFC 7231 Content-Language
- RFC 7231 Content-Location
- RFC 7230 Content-Length
- RFC 7233 Content-Range
- RFC 7230 Trailer
- RFC 7230 Transfer-Encoding
- RFC 7231 Content-Type
- RFC 7234 Age
- RFC 7234 Cache-Control
- RFC 7234 Expires
- RFC 7231 Date
- RFC 7231 Location
- RFC 7231 Retry-After
- RFC 7231 Vary
- RFC 7234 Warning
- RFC 7232 ETag
- RFC 7232 Last-Modified
- RFC 7235 WWW-Authenticate
- RFC 7235 Proxy-Authenticate
- RFC 7233 Accept-Ranges
- RFC 7231 Allow
- RFC 7231 Server
Example
Request
GET https://www.us.api.concursolutions.com/travel/v4/Users
Response
{
"id": "e83e6c1a-f4f2-456a-921e-cc8be49a2715",
"urn:ietf:params:scim:schemas:extension:travel:2.0:User":
{
"ruleClass": {
"name": "RC_1",
"id": 972
},
"travelCrsName": "",
"xmlProfileSyncId": "",
"travelNameRemark": "",
"orgUnit": Development,
"customFields": [],
"manager": "c2f98467-361e-446b-8b36-65e47c222605",
"groups": [
64165
]
}
}
Schema
Travel Extension
| Name | Type | Format | Description |
|---|---|---|---|
ruleClass |
complex |
- | Required Assigns the Concur Travel rule class for the travel user. Either Rule Class ID or Rule Class Name should be provided. Value must exactly match Travel Class name maintained in Travel. |
travelNameRemark |
string |
- | Concur Travel name remark. Can be used by TMCs to distinguish profiles where companies have multiple users with the same name. |
xmlProfileSyncId |
string |
- | A user-assigned Concur Travel user identifier that allows the user profile to be synchronized with other vendors. The following characters cannot be used as a value for this record: # ! * & ( ) ~ ' { - ^ } / ? > < , ; : " + = ] % |
travelCrsName |
string |
- | The name of the profile in the GDS system or GDS profile name. This value associates a Concur Travel profile to the GDS profile. |
orgUnit |
string |
- | Org unit for the user. Value must exactly match an Org unit or division value setup for the company. |
groups |
integer |
- | List of user groups that user belongs to for assigning travel roles. |
manager |
complex |
- | Travel approver of this user. Must match an existing employee in the travel database. |
customFields |
complex |
- | User can set values to custom data fields. |
Error
| Name | Type | Format | Description |
|---|---|---|---|
errorCode |
string |
- | Required Machine readable code associated with the error. |
errorMessage |
string |
- | Required Message associated with the error. |
USER
User
The Users resource represents a set of SAP Concur users. It is always managed as a batch of users, even if the batch contains only one user.
- Retrieve a user's information
- Retrieve all users based on search criteria
- Retrieve the list of required fields for creating a user
- Update a user's account information - Create a User is not supported at this time.
- Update a user's password
Version
1.0
Process Flow

Retrieve a User's Information
This resource allows you to get profile information for a given user. If a request URL does not include a ?loginID parameter then the response will be for the logged in user (and you must pass authentication information with your request).
GET api/user/v1.0/user
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
loginID |
string |
- | The URL-encoded SAP Concur login of the user. Optional. |
Get User Response Schema
| Name | Type | Format | Description |
|---|---|---|---|
loginID |
string |
- | The user's login ID. |
Active |
Boolean |
Y/N | Whether the user is currently active. |
FirstName |
string |
- | The user's first name. |
LastName |
string |
- | The user's last name. |
Mi |
string |
- | The user's middle initial. |
EmailAddress |
string |
- | The user's email address. |
EmpId |
string |
- | The unique identifier for the user. |
LedgerName |
string |
- | The user's assigned account code ledger. |
LocaleName |
string |
- | The user's language locale code. One of the Supported Locales. Example: United States English is en_US. |
OrgUnit1 through OrgUnit6 |
string |
- | Varies depending on configuration. |
Custom1 through Custom21 |
string |
- | Varies depending on configuration. If the custom field is a list field, the data will be returned as: (list item short code) list item name. List Field Example: |
CtryCode |
string |
2-character country code | The user's two-digit country code. |
CashAdvanceAccountCode |
string |
- | The user's account code for cash advances. |
CrnCode |
string |
ISO 4217 currency code | The user's three character reimbursement currency. Example: United States Dollar is USD. |
CtrySubCode |
string |
- | The user's two-digit country code and two-digit state or province code. Example: Washington State, United States is US-WA. |
ExpenseUser |
Boolean |
Y/N | Whether the user has access to Expense. |
ExpenseApprover |
Boolean |
Y/N | Whether the user is an Expense approver. |
TripUser |
Boolean |
Y/N | Whether the user has access to Travel. |
InvoiceUser |
Boolean |
Y/N | Whether the user has access to Invoice. |
InvoiceApprover |
Boolean |
Y/N | Whether the user is an Invoice approver. |
ExpenseApproverEmployeeID |
string |
- | The employee ID of the user's Expense approver. If you are importing both a user and their approver, the approver should be listed before the user in the batch. |
IsTestEmp |
Boolean |
Y/N | Whether the user is a test user. |
Retrieve All Users Based on Search Criteria
Note that this is a version 3.0 API and can be found here.
Retrieve the List of Required Fields for Creating a User
Retrieves a list of configured fields on the Global employee form in SAP Concur.
GET api/user/v1.0/FormFields
Required Fields Response Schema
| Name | Type | Format | Description |
|---|---|---|---|
Id |
string |
- | The unique field identifier. |
Label |
string |
- | The displayed field label. |
ControlType |
string |
- | The type of field. |
DataType |
string |
- | The type of data the field collects. |
MaxLength |
string |
- | The maximum length of data in the field. |
Required |
string |
- | Whether the field is required. |
Cols |
string |
- | The number of columns the field occupies. |
Access |
string |
- | The end-user access to the field. |
Width |
string |
- | The width of the field, in pixels. |
Custom |
string |
- | Whether the field is custom. |
Sequence |
string |
- | The sequence of the field on the form. |
These elements are returned for Custom fields only:
| Name | Type | Format | Description |
|---|---|---|---|
ParentFormTypeCode |
string |
- | This element is only populated for multi-level list fields. The type of form that the parent field (the field one level higher in the list hierarchy) is connected to. |
ParentFieldId |
string |
- | The identifier for the field one level higher in the list hierarchy. |
IsCopyDownSourceForOtherForms |
string |
- | Whether the field is used as a copy down source by other forms. |
ListName |
string |
- | The name of the list associated with the field. |
HierLevel |
string |
- | The list level of the field. If it is the second level field in a two-level list, the value would be 2. |
Update a User's Account Information
Updates one or more users. The batch can contain up to 500 users.
NOTE: The User API can be used to add new users, however the user accounts will not be fully configured and ready for use. Additional work to the user profiles must be completed, either with manual edits or updates via the user import, in order to complete the user profiles. There is a high degree of variability in customer configuration that is not all supported by this API. Manual edits or updates via a file import are most likely required to complete the User profiles started with this API. Only POST is supported. Please use the Employee Import feature if the User API does not meet your needs.
POST api/user/v1.0/users
This API requires as its arguments a batch element containing a UserProfile child element for each user to be added (in the future) or updated. The UserProfile child elements will vary depending on the form configuration, and may contain the following elements.
Update User Account Information Request Schema
| Name | Type | Format | Description |
|---|---|---|---|
EmpId |
string |
- | Required. The unique identifier for the user. The default value is the user's email address. Maximum 48 characters. |
FeedRecordNumber |
string |
- | Required. The record number in the current batch. |
LoginId |
string |
- | Required. The user's login ID. The default value is the user's email address. The value MUST have a '@'. Maximum 128 characters. |
LocaleName |
string |
- | The user's language locale code. List of locale codes are available in the Employee Import Appendix. One of the Supported Locales. Example: United States English is en_US. The supported languages vary by company but always include en_US. Maximum: 5 characters. |
Active |
Boolean |
Y/N | Whether the user is currently active. |
Password |
string |
- | Required. The user's password. This element can be used to enter the password for a new user, but cannot be used to update the password for an existing user. Maximum 255 characters. |
FirstName |
string |
- | The user's first name. Maximum 32 characters. |
LastName |
string |
- | The user's last name. Maximum 32 characters. |
Mi |
string |
- | The user's middle initial. Maximum 1 character. |
EmailAddress |
string |
- | The user's email address. Maximum 255 characters. |
LedgerKey |
string |
- | Required for new users. The user's assigned account code ledger. Example: Default. Maximum 20 characters. |
OrgUnit1 through OrgUnit6 |
string |
- | The custom organizational unit fields on the Employee form. Varies depending on configuration. Use the Employee Form Field resource to get the list of configured fields. Maximum 48 characters for each field. |
Custom1 through Custom21 |
string |
- | The custom fields on the Employee form. Varies depending on configuration. Use the Employee Form Field resource to get the list of configured fields. Maximum 48 characters. |
CtryCode |
string |
ISO 3166-1 alpha-2 country code | Country code, example: United States is US. Maximum 2 characters. |
CashAdvanceAccountCode |
string |
- | The user's account code for cash advances. Maximum 20 characters. |
CrnKey |
string |
ISO 4217 3-letter currency code | Currency code for the user's reimbursement currency. Example: United States Dollar is USD. Maximum 3 characters. |
CtrySubCode |
string |
- | The user's two-character country code and two-character state or province code. Example: Washington State, United States is US-WA. Maximum 2 characters. |
ExpenseUser |
Boolean |
Y/N |
Whether the user has access to Expense. |
ExpenseApprover |
Boolean |
Y/N |
Whether the user is an Expense approver. |
TripUser |
Boolean |
Y/N |
Whether the user has access to Travel. |
InvoiceUser |
Boolean |
Y/N |
Whether the user has access to Invoice. |
InvoiceApprover |
Boolean |
Y/N |
Whether the user is an Invoice approver. |
ExpenseApproverEmployeeID |
string |
- | The employee ID of the user's Expense approver. If you are importing both a user and their approver, the approver should be listed before the user in the batch. Maximum 48 characters. |
NewLoginID |
string |
- | Use this element to change the Login ID for an existing employee. Maximum 128 characters. |
NewEmployeeID |
string |
- | Use this element to change the Employee ID for an existing employee. Maximum 48 characters. |
Update User Account Information Response Schema
| Name | Type | Format | Description |
|---|---|---|---|
records-succeeded |
string |
- | The number of records processed that were successfully added or updated. |
records-failed |
string |
- | The number of records processed that were not successfully added or updated. |
When any users are successfully updated:
The request will return the UserDetails parent element with a UserInfo element for each successfully added or updated user. The UserInfo elements will contain the following child elements:
| Name | Type | Format | Description |
|---|---|---|---|
EmployeeID |
string |
- | The employee ID of the user. |
FeedRecordNumber |
string |
- | The item number of the record in the feed. |
Status |
string |
- | The status of the attempt to add or update the user. Should always contain the word SUCCESS. |
When any users fail:
The request will return the errors parent element with an error parent element for each record failure. The error element will contain the following child elements:
| Name | Type | Format | Description |
|---|---|---|---|
EmployeeID |
string |
- | The employee ID of the user. |
FeedRecordNumber |
string |
- | The item number of the record in the feed. |
Message |
string |
- | The error message. |
Example
<batch xmlns="http://www.concursolutions.com/api/user/2011/02">
<UserProfile>
<LoginID>loginID</LoginID>
<EmployeeID>employeeID</EmployeeID>
<Active>N</Active>
<--! Any more required fields -->
</UserProfile>
</batch>
Update a User's Password
POST api/user/v1.0/Users/password
Updates passwords for up to 500 users.
Please keep in mind that this method will not update the user password expiry date, if you are updating the password to overcome password expiration policy. User will still have to change his password when they login to SAP Concur if the original password before update was expired.
Update User's Password Request Schema
This function requires as its arguments a UserBatch element containing a User child element for each user. The User element must have the following elements:
| Name | Type | Format | Description |
|---|---|---|---|
LoginID |
string |
- | Required. The user's login ID. The default value is the user's email address. The value MUST contain '@'. |
Password |
string |
- | The user's new password. |
Update User's Password Response Schema
This request will return a BatchResult parent element with the following child elements:
| Name | Type | Format | Description |
|---|---|---|---|
RecordsSucceeded |
string |
- | The number of records processed that were successfully updated. |
RecordsFailed |
string |
- | The number of records processed that were not successfully updated. |
UserPasswordStatusList |
string |
- | This parent element will contains a UserPasswordStatus element for each user. |
The UserPasswordStatus element contains the following child elements:
| Name | Type | Format | Description |
|---|---|---|---|
LoginID |
string |
- | The login ID of the user. |
Status |
Boolean |
Success/Failed | The status of the attempt to update the user's password. |
Message |
string |
- | Additional details about the success or failure of the request. |
Example
<UserBatch xmlns="http://www.concursolutions.com/api/user/2011/02">
<User>
<LoginID>loginID</LoginID>
<Password>password</Password>
</User>
</UserBatch>